octave-libgccjit: doc/interpreter/diagperm.txi annotate

annotate doc/interpreter/diagperm.txi @ 8917:d707aa3bbc36

manual improvements

author	Jaroslav Hajek <highegg@gmail.com>
date	Fri, 06 Mar 2009 13:42:24 +0100
parents	46fdf8714acf
children	349616d9c38e

rev	line source
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	1 @c Copyright (C) 2009 Jaroslav Hajek
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	2 @c
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	3 @c This file is part of Octave.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	4 @c
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	5 @c Octave is free software; you can redistribute it and/or modify it
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	6 @c under the terms of the GNU General Public License as published by the
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	7 @c Free Software Foundation; either version 3 of the License, or (at
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	8 @c your option) any later version.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	9 @c
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	10 @c Octave is distributed in the hope that it will be useful, but WITHOUT
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	13 @c for more details.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	14 @c
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	15 @c You should have received a copy of the GNU General Public License
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	16 @c along with Octave; see the file COPYING. If not, see
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	17 @c <http://www.gnu.org/licenses/>.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	18
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	19 @node Diagonal and Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	20 @chapter Diagonal and Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	21
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	22 @menu
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	23 * Basic Usage:: Creation and Manipulation of Diagonal and Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	24 * Matrix Algebra:: Linear Algebra with Diagonal and Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	25 * Function Support:: Functions That Are Aware of These Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	26 * Example Codes:: Some Examples of Usage
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	27 * Zeros Treatment:: The Differences in Treatment of Zero Elements
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	28 @end menu
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	29
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	30 @node Basic Usage
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	31 @section Creating and Manipulating Diagonal and Permutation Matrices
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	32
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	33 A diagonal matrix is defined as a matrix that has zero entries outside the main diagonal;
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	34 that is,
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	35 @iftex
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	36 @tex
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	37 $D_{ij} = 0$ if $i \neq j$
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	38 @end tex
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	39 @end iftex
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	40 @ifnottex
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	41 @code{D(i,j) == 0} if @code{i != j}.
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	42 @end ifnottex
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	43 Most often, square diagonal matrices are considered; however, the definition can equally
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	44 be applied to nonsquare matrices, in which case we usually speak of a rectangular diagonal
8859 46fdf8714acf remove url hrefs from diagperm.txi Jaroslav Hajek <highegg@gmail.com> parents: 8851 diff changeset	45 matrix.
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	46
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	47 A permutation matrix is defined as a square matrix that has a single element equal to unity
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	48 in each row and each column; all other elements are zero. That is, there exists a
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	49 permutation (vector)
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	50 @iftex
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	51 @tex
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	52 $p$ such that $P_{ij}=1$ if $j = p_i$ and
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	53 $P_{ij}=0$ otherwise.
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	54 @end tex
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	55 @end iftex
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	56 @ifnottex
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	57 @code{p} such that @code{P(i,j) == 1} if @code{j == p(i)} and
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	58 @code{P(i,j) == 0} otherwise.
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	59 @end ifnottex
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	60
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	61 Octave provides special treatment of real and complex rectangular diagonal matrices,
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	62 as well as permutation matrices. They are stored as special objects, using efficient
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	63 storage and algorithms, facilitating writing both readable and efficient matrix algebra
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	64 expressions in the Octave language.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	65
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	66 @menu
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	67 * Creating Diagonal Matrices::
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	68 * Creating Permutation Matrices::
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	69 * Explicit and Implicit Conversions::
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	70 @end menu
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	71
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	72 @node Creating Diagonal Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	73 @subsection Creating Diagonal Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	74
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	75 The most common and easiest way to create a diagonal matrix is using the built-in
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	76 function @dfn{diag}. The expression @code{diag (v)}, with @var{v} a vector,
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	77 will create a square diagonal matrix with elements on the main diagonal given
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	78 by the elements of @var{v}, and size equal to the length of @var{v}.
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	79 @code{diag (v, m, n)} can be used to construct a rectangular diagonal matrix.
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	80 The result of these expressions will be a special diagonal matrix object, rather
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	81 than a general matrix object.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	82
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	83 Diagonal matrix with unit elements can be created using @dfn{eye}.
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	84 Some other built-in functions can also return diagonal matrices. Examples include
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	85 @dfn{balance} or @dfn{inv}.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	86
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	87 Example:
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	88 @example
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	89 diag (1:4)
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	90 @result{}
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	91 Diagonal Matrix
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	92
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	93 1 0 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	94 0 2 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	95 0 0 3 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	96 0 0 0 4
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	97
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	98 diag(1:3,5,3)
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	99
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	100 @result{}
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	101 Diagonal Matrix
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	102
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	103 1 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	104 0 2 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	105 0 0 3
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	106 0 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	107 0 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	108 @end example
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	109
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	110 @node Creating Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	111 @subsection Creating Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	112
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	113 For creating permutation matrices, Octave does not introduce a new function, but
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	114 rather overrides an existing syntax: permutation matrices can be conveniently
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	115 created by indexing an identity matrix by permutation vectors.
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	116 That is, if @var{q} is a permutation vector of length @var{n}, the expression
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	117 @example
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	118 P = eye (n) (:, q);
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	119 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	120 will create a permutation matrix - a special matrix object.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	121 @example
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	122 eye (n) (q, :)
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	123 @end example
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	124 will also work (and create a row permutation matrix), as well as
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	125 @example
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	126 eye (n) (q1, q2).
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	127 @end example
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	128
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	129 For example:
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	130 @example
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	131 eye (4) ([1,3,2,4],:)
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	132 @result{}
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	133 Permutation Matrix
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	134
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	135 1 0 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	136 0 0 1 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	137 0 1 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	138 0 0 0 1
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	139
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	140 eye (4) (:,[1,3,2,4])
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	141 @result{}
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	142 Permutation Matrix
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	143
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	144 1 0 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	145 0 0 1 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	146 0 1 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	147 0 0 0 1
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	148 @end example
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	149
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	150 Mathematically, an identity matrix is both diagonal and permutation matrix.
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	151 In Octave, @code{eye (n)} returns a diagonal matrix, because a matrix
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	152 can only have one class. You can convert this diagonal matrix to a permutation
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	153 matrix by indexing it by an identity permutation, as shown below.
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	154 This is a special property of the identity matrix; indexing other diagonal
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	155 matrices generally produces a full matrix.
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	156
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	157 @example
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	158 eye (3)
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	159 @result{}
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	160 Diagonal Matrix
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	161
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	162 1 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	163 0 1 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	164 0 0 1
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	165
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	166 eye(3)(1:3,:)
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	167 @result{}
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	168 Permutation Matrix
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	169
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	170 1 0 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	171 0 1 0
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	172 0 0 1
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	173 @end example
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	174
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	175 Some other built-in functions can also return permutation matrices. Examples include
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	176 @dfn{inv} or @dfn{lu}.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	177
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	178 @node Explicit and Implicit Conversions
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	179 @subsection Explicit and Implicit Conversions
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	180
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	181 The diagonal and permutation matrices are special objects in their own right. A number
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	182 of operations and built-in functions are defined for these matrices to use special,
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	183 more efficient code than would be used for a full matrix in the same place. Examples
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	184 are given in further sections.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	185
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	186 To facilitate smooth mixing with full matrices, backward compatibility, and
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	187 compatibility with Matlab, the diagonal and permutation matrices should allow
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	188 any operation that works on full matrices, and will either treat it specially,
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	189 or implicitly convert themselves to full matrices.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	190
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	191 Instances include matrix indexing, except for extracting a single element or
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	192 a leading submatrix, indexed assignment, or applying most mapper functions,
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	193 such as @dfn{exp}.
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	194
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	195 An explicit conversion to a full matrix can be requested using the built-in
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	196 function @dfn{full}. It should also be noted that the diagonal and permutation
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	197 matrix objects will cache the result of the conversion after it is first
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	198 requested (explicitly or implicitly), so that subsequent conversions will
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	199 be very cheap.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	200
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	201 @node Matrix Algebra
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	202 @section Linear Algebra with Diagonal and Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	203
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	204 As has been already said, diagonal and permutation matrices make it
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	205 possible to use efficient algorithms while preserving natural linear
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	206 algebra syntax. This section describes in detail the operations that
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	207 are treated specially when performed on these special matrix objects.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	208
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	209 @menu
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	210 * Expressions Involving Diagonal Matrices::
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	211 * Expressions Involving Permutation Matrices::
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	212 @end menu
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	213
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	214 @node Expressions Involving Diagonal Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	215 @subsection Expressions Involving Diagonal Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	216
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	217 Assume @var{D} is a diagonal matrix. If @var{M} is a full matrix,
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	218 then @code{D*M} will scale the rows of @var{M}. That means,
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	219 if @code{S = D*M}, then for each pair of indices
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	220 i,j it holds
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	221 @iftex
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	222 @tex
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	223 $$S_{ij} = D_{ii} M_{ij}$$
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	224 @end tex
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	225 @end iftex
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	226 @ifnottex
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	227 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	228 S(i,j) = D(i,i) * M(i,j).
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	229 @end example
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	230 @end ifnottex
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	231 Similarly, @code{M*D} will do a column scaling.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	232
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	233 The matrix @var{D} may also be rectangular, m-by-n where @code{m != n}.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	234 If @code{m < n}, then the expression @code{D*M} is equivalent to
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	235 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	236 D(:,1:m) * M(1:m,:),
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	237 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	238 i.e. trailing @code{n-m} rows of @var{M} are ignored. If @code{m > n},
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	239 then @code{D*M} is equivalent to
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	240 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	241 [D(1:n,n) * M; zeros(m-n, columns (M))],
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	242 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	243 i.e. null rows are appended to the result.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	244 The situation for right-multiplication @code{M*D} is analogous.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	245
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	246 The expressions @code{D \ M} and @code{M / D} perform inverse scaling.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	247 They are equivalent to solving a diagonal (or rectangular diagonal)
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	248 in a least-squares minimum-norm sense. In exact arithmetics, this is
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	249 equivalent to multiplying by a pseudoinverse. The pseudoinverse of
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	250 a rectangular diagonal matrix is again a rectangular diagonal matrix
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	251 with swapped dimensions, where each nonzero diagonal element is replaced
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	252 by its reciprocal.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	253 The matrix division algorithms do, in fact, use division rather than
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	254 multiplication by reciprocals for better numerical accuracy; otherwise, they
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	255 honor the above definition. Note that a diagonal matrix is never truncated due
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	256 to ill-conditioning; otherwise, it would not be much useful for scaling. This
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	257 is typically consistent with linear algebra needs. A full matrix that only
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	258 happens to be diagonal (an is thus not a special object) is of course treated
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	259 normally.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	260
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	261 If @var{D1} and @var{D2} are both diagonal matrices, then the expressions
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	262 @example
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	263 D1 + D2
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	264 D1 - D2
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	265 D1 * D2
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	266 D1 / D2
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	267 D1 \ D2
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	268 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	269 again produce diagonal matrices, provided that normal
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	270 dimension matching rules are obeyed. The relations used are same as described above.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	271
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	272 Also, a diagonal matrix @var{D} can be multiplied or divided by a scalar, or raised
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	273 to a scalar power if it is square, producing diagonal matrix result in all cases.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	274
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	275 A diagonal matrix can also be transposed or conjugate-transposed, giving the expected
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	276 result. Extracting a leading submatrix of a diagonal matrix, i.e. @code{D(1:m,1:n)},
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	277 will produce a diagonal matrix, other indexing expressions will implicitly convert to
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	278 full matrix.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	279
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	280 Adding a diagonal matrix to a full matrix only operates on the diagonal elements. Thus,
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	281 @example
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	282 A = A + eps * eye (n)
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	283 @end example
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	284 is an efficient method of augmenting the diagonal of a matrix. Subtraction works
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	285 analogically.
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	286
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	287 When involved in expressions with other element-by-element operators, @code{.*},
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	288 @code{./}, @code{.\} or @code{.^}, an implicit conversion to full matrix will
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	289 take place. This is not always strictly necessary but chosen to facilitate
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	290 better consistency with Matlab.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	291
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	292 @node Expressions Involving Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	293 @subsection Expressions Involving Permutation Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	294
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	295 If @var{P} is a permutation matrix and @var{M} a matrix, the expression
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	296 @code{PM} will permute the rows of @var{M}. Similarly, @code{MP} will
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	297 yield a column permutation.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	298 Matrix division @code{P\M} and @code{M/P} can be used to do inverse permutation.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	299
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	300 The previously described syntax for creating permutation matrices can actually
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	301 help an user to understand the connection between a permutation matrix and
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	302 a permuting vector. Namely, the following holds, where @code{I = eye (n)}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	303 is an identity matrix:
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	304 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	305 I(p,:) * M = (I*M) (p,:) = M(p,:)
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	306 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	307 Similarly,
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	308 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	309 M * I(:,p) = (M*I) (:,p) = M(:,p)
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	310 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	311
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	312 The expressions @code{I(p,:)} and @code{I(:,p)} are permutation matrices.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	313
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	314 A permutation matrix can be transposed (or conjugate-transposed, which is the
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	315 same, because a permutation matrix is never complex), inverting the
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	316 permutation, or equivalently, turning a row-permutation matrix into a
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	317 column-permutation one. For permutation matrices, transpose is equivalent to
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	318 inversion, thus @code{P\M} is equivalent to @code{P'*M}. Transpose of a
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	319 permutation matrix (or inverse) is a constant-time operation, flipping only a
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	320 flag internally, and thus the choice between the two above equivalent
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	321 expressions for inverse permuting is completely up to the user's taste.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	322
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	323 Two permutation matrices can be multiplied or divided (if their sizes match), performing
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	324 a composition of permutations. Also a permutation matrix can be indexed by a permutation
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	325 vector (or two vectors), giving again a permutation matrix.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	326 Any other operations do not generally yield a permutation matrix and will thus
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	327 trigger the implicit conversion.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	328
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	329 @node Function Support
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	330 @section Functions That Are Aware of These Matrices
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	331
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	332 This section lists the built-in functions that are aware of diagonal and
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	333 permutation matrices on input, or can return them as output. Passed to other
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	334 functions, these matrices will in general trigger an implicit conversion.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	335 (Of course, user-defined dynamically linked functions may also work with
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	336 diagonal or permutation matrices).
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	337
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	338 @menu
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	339 * Diagonal Matrix Functions::
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	340 * Permutation Matrix Functions::
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	341 @end menu
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	342
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	343 @node Diagonal Matrix Functions
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	344 @subsection Diagonal Matrix Functions
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	345
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	346 @dfn{inv} and @dfn{pinv} can be applied to a diagonal matrix, yielding again
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	347 a diagonal matrix. @dfn{det} will use an efficient straightforward calculation
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	348 when given a diagonal matrix, as well as @dfn{cond}.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	349 The following mapper functions can be applied to a diagonal matrix
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	350 without converting it to a full one:
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	351 @dfn{abs}, @dfn{real}, @dfn{imag}, @dfn{conj}, @dfn{sqrt}.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	352 A diagonal matrix can also be returned from the @dfn{balance}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	353 and @dfn{svd} functions.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	354
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	355 @node Permutation Matrix Functions
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	356 @subsection Permutation Matrix Functions
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	357
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	358 @dfn{inv} and @dfn{pinv} will invert a permutation matrix, preserving its
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	359 specialness. @dfn{det} can be applied to a permutation matrix, efficiently
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	360 calculating the sign of the permutation (which is equal to the determinant).
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	361
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	362 A permutation matrix can also be returned from the built-in functions
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	363 @dfn{lu} and @dfn{qr}, if a pivoted factorization is requested.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	364
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	365 @node Example Codes
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	366 @section Some Examples of Usage
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	367
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	368 The following can be used to solve a linear system @code{A*x = b}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	369 using the pivoted LU factorization:
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	370 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	371 [L, U, P] = lu (A); ## now LU = PA
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	372 x = U \ L \ P*b;
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	373 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	374
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	375 @noindent
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	376 This is how you normalize columns of a matrix @var{X} to unit norm:
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	377 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	378 s = norm (X, "columns");
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	379 X = diag (s) \ X;
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	380 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	381
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	382 @noindent
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	383 The following expression is a way to efficiently calculate the sign of a
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	384 permutation, given by a permutation vector @var{p}. It will also work
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	385 in earlier versions of Octave, but slowly.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	386 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	387 det (eye (length (p))(p, :))
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	388 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	389
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	390 @noindent
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	391 Finally, here's how you solve a linear system @code{A*x = b}
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	392 with Tikhonov regularization (ridge regression) using SVD (a skeleton only):
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	393 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	394 m = rows (A); n = columns (A);
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	395 [U, S, V] = svd (A);
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	396 ## determine the regularization factor alpha
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	397 ## alpha = ...
d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	398 ## transform to orthogonal basis
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	399 b = U'*b;
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	400 ## Use the standard formula, replacing A with S.
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	401 ## S is diagonal, so the following will be very fast and accurate.
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	402 x = (S'S + alpha^2 eye (n)) \ (S' * b);
8851 d6de39523f03 improve the diag & perm matrices text Jaroslav Hajek <highegg@gmail.com> parents: 8839 diff changeset	403 ## transform to solution basis
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	404 x = V*x;
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	405 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	406
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	407
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	408 @node Zeros Treatment
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	409 @section The Differences in Treatment of Zero Elements
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	410
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	411 Making diagonal and permutation matrices special matrix objects in their own
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	412 right and the consequent usage of smarter algorithms for certain operations
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	413 implies, as a side effect, small differences in treating zeros.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	414 The contents of this section applies also to sparse matrices, discussed in
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	415 the following chapter.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	416
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	417 The IEEE standard defines the result of the expressions @code{0*Inf} and
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	418 @code{0*NaN} as @code{NaN}, as it has been generally agreed that this is the
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	419 best compromise.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	420 Numerical software dealing with structured and sparse matrices (including
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	421 Octave) however, almost always makes a distinction between a "numerical zero"
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	422 and an "assumed zero".
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	423 A "numerical zero" is a zero value occuring in a place where any floating-point
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	424 value could occur. It is normally stored somewhere in memory as an explicit
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	425 value.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	426 An "assumed zero", on the contrary, is a zero matrix element implied by the
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	427 matrix structure (diagonal, triangular) or a sparsity pattern; its value is
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	428 usually not stored explicitly anywhere, but is implied by the underlying
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	429 data structure.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	430
8917 d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	431 The primary distinction is that an assumed zero, when multiplied
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	432 by any number, or divided by any nonzero number,
d707aa3bbc36 manual improvements Jaroslav Hajek <highegg@gmail.com> parents: 8859 diff changeset	433 yields always a zero, even when, e.g., multiplied by @code{Inf}
8839 fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	434 or divided by @code{NaN}.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	435 The reason for this behavior is that the numerical multiplication is not
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	436 actually performed anywhere by the underlying algorithm; the result is
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	437 just assumed to be zero. Equivalently, one can say that the part of the
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	438 computation involving assumed zeros is performed symbolically, not numerically.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	439
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	440 This behavior not only facilitates the most straightforward and efficient
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	441 implementation of algorithms, but also preserves certain useful invariants,
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	442 like:
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	443 @itemize
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	444 @item scalar * diagonal matrix is a diagonal matrix
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	445 @item sparse matrix / scalar preserves the sparsity pattern
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	446 @item permutation matrix * matrix is equivalent to permuting rows
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	447 @end itemize
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	448 all of these natural mathematical truths would be invalidated by treating
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	449 assumed zeros as numerical ones.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	450
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	451 Note that certain competing software does not strictly follow this principle
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	452 and converts assumed zeros to numerical zeros in certain cases, while not doing
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	453 so in other cases. As of today, there are no intentions to mimick such behavior
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	454 in Octave.
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	455
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	456 Examples of effects of assumed zeros vs. numerical zeros:
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	457 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	458 Inf * eye (3)
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	459 @result{}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	460 Inf 0 0
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	461 0 Inf 0
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	462 0 0 Inf
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	463
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	464 Inf * speye (3)
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	465 @result{}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	466 Compressed Column Sparse (rows = 3, cols = 3, nnz = 3 [33%])
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	467
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	468 (1, 1) -> Inf
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	469 (2, 2) -> Inf
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	470 (3, 3) -> Inf
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	471
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	472 Inf * full (eye (3))
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	473 @result{}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	474 Inf NaN NaN
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	475 NaN Inf NaN
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	476 NaN NaN Inf
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	477
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	478 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	479
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	480 @example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	481 diag(1:3) * [NaN; 1; 1]
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	482 @result{}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	483 NaN
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	484 2
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	485 3
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	486
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	487 sparse(1:3,1:3,1:3) * [NaN; 1; 1]
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	488 @result{}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	489 NaN
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	490 2
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	491 3
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	492 [1,0,0;0,2,0;0,0,3] * [NaN; 1; 1]
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	493 @result{}
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	494 NaN
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	495 NaN
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	496 NaN
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	497 @end example
fcba62cc4549 add chapter about diagonal and permutation matrices to manual Jaroslav Hajek <highegg@gmail.com> parents: diff changeset	498

Mercurial > octave-libgccjit

annotate doc/interpreter/diagperm.txi @ 8917:d707aa3bbc36