Mercurial > hg > octave-avbm
changeset 12584:7ef7e20057fa stable
Improve documentation strings in Linear Algebra chapter.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Fri, 08 Apr 2011 12:44:40 -0700 |
parents | 6a4e042b6114 |
children | c3d4542a4f06 |
files | scripts/ChangeLog scripts/linear-algebra/cond.m scripts/linear-algebra/expm.m scripts/linear-algebra/logm.m scripts/linear-algebra/null.m scripts/linear-algebra/orth.m scripts/linear-algebra/rank.m scripts/linear-algebra/rref.m src/ChangeLog src/DLD-FUNCTIONS/balance.cc src/DLD-FUNCTIONS/eig.cc src/DLD-FUNCTIONS/hess.cc src/DLD-FUNCTIONS/pinv.cc src/DLD-FUNCTIONS/schur.cc src/DLD-FUNCTIONS/sqrtm.cc src/DLD-FUNCTIONS/svd.cc src/data.cc |
diffstat | 17 files changed, 94 insertions(+), 170 deletions(-) [+] |
line wrap: on
line diff
--- a/scripts/ChangeLog +++ b/scripts/ChangeLog @@ -1,3 +1,9 @@ +2011-04-08 Rik <octave@nomad.inbox5.com> + + * linear-algebra/cond.m, linear-algebra/expm.m, linear-algebra/logm.m, + linear-algebra/null.m, linear-algebra/orth.m, linear-algebra/rank.m, + linear-algebra/rref.m: Improve docstrings. + 2011-04-06 Rik <octave@nomad.inbox5.com> * miscellaneous/pack.m: Improve docstring.
--- a/scripts/linear-algebra/cond.m +++ b/scripts/linear-algebra/cond.m @@ -19,9 +19,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} cond (@var{A}) ## @deftypefnx {Function File} {} cond (@var{A}, @var{p}) -## Compute the @var{p}-norm condition number of a matrix. @code{cond -## (@var{A})} is -## defined as +## Compute the @var{p}-norm condition number of a matrix. +## +## @code{cond (@var{A})} is ## defined as ## @tex ## $ {\parallel A \parallel_p * \parallel A^{-1} \parallel_p .} $ ## @end tex
--- a/scripts/linear-algebra/expm.m +++ b/scripts/linear-algebra/expm.m @@ -68,6 +68,7 @@ ## @code{Dq(A)} ## @end ifnottex ## is ill-conditioned. +## @seealso{logm, sqrtm} ## @end deftypefn function r = expm (A)
--- a/scripts/linear-algebra/logm.m +++ b/scripts/linear-algebra/logm.m @@ -32,7 +32,7 @@ ## The optional argument @var{opt_iters} is the maximum number of square roots ## to compute and defaults to 100. The optional output @var{iters} is the ## number of square roots actually computed. -## +## @seealso{expm, sqrtm} ## @end deftypefn ## Reference: N. J. Higham, Functions of Matrices: Theory and Computation
--- a/scripts/linear-algebra/null.m +++ b/scripts/linear-algebra/null.m @@ -17,7 +17,8 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} null (@var{A}, @var{tol}) +## @deftypefn {Function File} {} null (@var{A}) +## @deftypefnx {Function File} {} null (@var{A}, @var{tol}) ## Return an orthonormal basis of the null space of @var{A}. ## ## The dimension of the null space is taken as the number of singular
--- a/scripts/linear-algebra/orth.m +++ b/scripts/linear-algebra/orth.m @@ -17,7 +17,8 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} orth (@var{A}, @var{tol}) +## @deftypefn {Function File} {} orth (@var{A}) +## @deftypefnx {Function File} {} orth (@var{A}, @var{tol}) ## Return an orthonormal basis of the range space of @var{A}. ## ## The dimension of the range space is taken as the number of singular
--- a/scripts/linear-algebra/rank.m +++ b/scripts/linear-algebra/rank.m @@ -17,7 +17,8 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} rank (@var{A}, @var{tol}) +## @deftypefn {Function File} {} rank (@var{A}) +## @deftypefnx {Function File} {} rank (@var{A}, @var{tol}) ## Compute the rank of @var{A}, using the singular value decomposition. ## The rank is taken to be the number of singular values of @var{A} that ## are greater than the specified tolerance @var{tol}. If the second
--- a/scripts/linear-algebra/rref.m +++ b/scripts/linear-algebra/rref.m @@ -17,9 +17,10 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {[@var{r}, @var{k}] =} rref (@var{A}, @var{tol}) -## -## Returns the reduced row echelon form of @var{A}. @var{tol} defaults +## @deftypefn {Function File} {} rref (@var{A}) +## @deftypefnx {Function File} {} rref (@var{A}, @var{tol}) +## @deftypefnx {Function File} {[@var{r}, @var{k}] =} rref (@dots{}) +## Return the reduced row echelon form of @var{A}. @var{tol} defaults ## to @code{eps * max (size (@var{A})) * norm (@var{A}, inf)}. ## ## Called with two return arguments, @var{k} returns the vector of
--- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,10 @@ +2011-04-08 Rik <octave@nomad.inbox5.com> + + * DLD-FUNCTIONS/balance.cc, DLD-FUNCTIONS/eig.cc, + DLD-FUNCTIONS/hess.cc, DLD-FUNCTIONS/pinv.cc, DLD-FUNCTIONS/schur.cc, + DLD-FUNCTIONS/sqrtm.cc, DLD-FUNCTIONS/svd.cc, data.cc: Improve + docstrings. + 2011-04-06 Rik <octave@nomad.inbox5.com> * DLD-FUNCTIONS/dmperm.cc, data.cc: Clean up operator and function
--- a/src/DLD-FUNCTIONS/balance.cc +++ b/src/DLD-FUNCTIONS/balance.cc @@ -62,9 +62,9 @@ calculation are typically improved by balancing first.\n\ \n\ If two output values are requested, @code{balance} returns \n\ -the diagonal @var{D} and the permutation @var{P} separately as vectors. \n\ -In this case, @code{@var{DD} = eye(n)(:,@var{P}) * diag (@var{D})}, where n\n\ -@t{n} is the matrix size. \n\ +the diagonal @var{D} and the permutation @var{P} separately as vectors.\n\ +In this case, @code{@var{DD} = eye(n)(:,@var{P}) * diag (@var{D})}, where\n\ +@math{n} is the matrix size. \n\ \n\ If four output values are requested, compute @code{@var{AA} =\n\ @var{CC}*@var{A}*@var{DD}} and @code{@var{BB} = @var{CC}*@var{B}*@var{DD}},\n\
--- a/src/DLD-FUNCTIONS/eig.cc +++ b/src/DLD-FUNCTIONS/eig.cc @@ -39,11 +39,12 @@ @deftypefnx {Loadable Function} {@var{lambda} =} eig (@var{A}, @var{B})\n\ @deftypefnx {Loadable Function} {[@var{V}, @var{lambda}] =} eig (@var{A})\n\ @deftypefnx {Loadable Function} {[@var{V}, @var{lambda}] =} eig (@var{A}, @var{B})\n\ -The eigenvalues (and eigenvectors) of a matrix are computed in a several\n\ -step process which begins with a Hessenberg decomposition, followed by a\n\ -Schur@tie{}decomposition, from which the eigenvalues are apparent. The\n\ -eigenvectors, when desired, are computed by further manipulations of the\n\ -Schur@tie{}decomposition.\n\ +Compute the eigenvalues and eigenvectors of a matrix.\n\ +\n\ +Eigenvalues are computed in a several step process which begins with a\n\ +Hessenberg decomposition, followed by a Schur@tie{}decomposition, from which\n\ +the eigenvalues are apparent. The eigenvectors, when desired, are computed\n\ +by further manipulations of the Schur@tie{}decomposition.\n\ \n\ The eigenvalues returned by @code{eig} are not ordered.\n\ @seealso{eigs, svd}\n\
--- a/src/DLD-FUNCTIONS/hess.cc +++ b/src/DLD-FUNCTIONS/hess.cc @@ -37,8 +37,8 @@ DEFUN_DLD (hess, args, nargout, "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {@var{h} =} hess (@var{A})\n\ -@deftypefnx {Loadable Function} {[@var{p}, @var{h}] =} hess (@var{A})\n\ +@deftypefn {Loadable Function} {@var{H} =} hess (@var{A})\n\ +@deftypefnx {Loadable Function} {[@var{P}, @var{H}] =} hess (@var{A})\n\ @cindex Hessenberg decomposition\n\ Compute the Hessenberg decomposition of the matrix @var{A}.\n\ \n\ @@ -51,8 +51,8 @@ is upper Hessenberg ($H_{i,j} = 0, \\forall i \\ge j+1$).\n\ @end tex\n\ @ifnottex\n\ -@code{@var{P} * @var{H} * @var{P}' = @var{A}} where @var{p} is a square\n\ -unitary matrix (@code{@var{p}' * @var{p} = I}, using complex-conjugate\n\ +@code{@var{P} * @var{H} * @var{P}' = @var{A}} where @var{P} is a square\n\ +unitary matrix (@code{@var{P}' * @var{P} = I}, using complex-conjugate\n\ transposition) and @var{H} is upper Hessenberg\n\ (@code{@var{H}(i, j) = 0 forall i >= j+1)}.\n\ @end ifnottex\n\
--- a/src/DLD-FUNCTIONS/pinv.cc +++ b/src/DLD-FUNCTIONS/pinv.cc @@ -43,7 +43,7 @@ Return the pseudoinverse of @var{x}. Singular values less than\n\ @var{tol} are ignored. \n\ \n\ -If the second argument is omitted, it is assumed that\n\ +If the second argument is omitted, it is taken to be\n\ \n\ @example\n\ tol = max (size (@var{x})) * sigma_max (@var{x}) * eps,\n\
--- a/src/DLD-FUNCTIONS/schur.cc +++ b/src/DLD-FUNCTIONS/schur.cc @@ -63,167 +63,64 @@ @deftypefnx {Loadable Function} {@var{S} =} schur (@var{A}, \"complex\")\n\ @deftypefnx {Loadable Function} {[@var{U}, @var{S}] =} schur (@var{A}, @var{opt})\n\ @cindex Schur decomposition\n\ -The Schur@tie{}decomposition is used to compute eigenvalues of a\n\ -square matrix, and has applications in the solution of algebraic\n\ -Riccati equations in control (see @code{are} and @code{dare}).\n\ -@code{schur} always returns\n\ +Compute the Schur@tie{}decomposition of @var{A}\n\ @tex\n\ -$S = U^T A U$\n\ +$$\n\ + S = U^T A U\n\ +$$\n\ @end tex\n\ @ifnottex\n\ +\n\ +@example\n\ @code{@var{S} = @var{U}' * @var{A} * @var{U}}\n\ +@end example\n\ +\n\ @end ifnottex\n\ -where\n\ -@tex\n\ -$U$\n\ -@end tex\n\ -@ifnottex\n\ -@var{U}\n\ -@end ifnottex\n\ - is a unitary matrix\n\ +where @var{U} is a unitary matrix\n\ @tex\n\ ($U^T U$ is identity)\n\ @end tex\n\ @ifnottex\n\ (@code{@var{U}'* @var{U}} is identity)\n\ @end ifnottex\n\ -and\n\ -@tex\n\ -$S$\n\ -@end tex\n\ -@ifnottex\n\ -@var{S}\n\ -@end ifnottex\n\ -is upper triangular. The eigenvalues of\n\ -@tex\n\ -$A$ (and $S$)\n\ -@end tex\n\ -@ifnottex\n\ -@var{A} (and @var{S})\n\ -@end ifnottex\n\ -are the diagonal elements of\n\ -@tex\n\ -$S$.\n\ -@end tex\n\ -@ifnottex\n\ -@var{S}.\n\ -@end ifnottex\n\ -If the matrix\n\ -@tex\n\ -$A$\n\ -@end tex\n\ -@ifnottex\n\ -@var{A}\n\ -@end ifnottex\n\ +and @var{S} is upper triangular. The eigenvalues of @var{A} (and @var{S})\n\ +are the diagonal elements of @var{S}. If the matrix @var{A}\n\ is real, then the real Schur@tie{}decomposition is computed, in which the\n\ -matrix\n\ -@tex\n\ -$U$\n\ -@end tex\n\ -@ifnottex\n\ -@var{U}\n\ -@end ifnottex\n\ -is orthogonal and\n\ -@tex\n\ -$S$\n\ -@end tex\n\ -@ifnottex\n\ -@var{S}\n\ -@end ifnottex\n\ -is block upper triangular\n\ +matrix @var{U} is orthogonal and @var{S} is block upper triangular\n\ with blocks of size at most\n\ @tex\n\ -$2\\times 2$\n\ +$2 \\times 2$\n\ @end tex\n\ @ifnottex\n\ @code{2 x 2}\n\ @end ifnottex\n\ -along the diagonal. The diagonal elements of\n\ -@tex\n\ -$S$\n\ -@end tex\n\ -@ifnottex\n\ -@var{S}\n\ -@end ifnottex\n\ +along the diagonal. The diagonal elements of @var{S}\n\ (or the eigenvalues of the\n\ @tex\n\ -$2\\times 2$\n\ +$2 \\times 2$\n\ @end tex\n\ @ifnottex\n\ @code{2 x 2}\n\ @end ifnottex\n\ -blocks, when\n\ -appropriate) are the eigenvalues of\n\ -@tex\n\ -$A$\n\ -@end tex\n\ -@ifnottex\n\ -@var{A}\n\ -@end ifnottex\n\ -and\n\ -@tex\n\ -$S$.\n\ -@end tex\n\ -@ifnottex\n\ -@var{S}.\n\ -@end ifnottex\n\ +blocks, when appropriate) are the eigenvalues of @var{A} and @var{S}.\n\ \n\ A complex decomposition may be forced by passing \"complex\" as @var{opt}.\n\ \n\ The eigenvalues are optionally ordered along the diagonal according to\n\ the value of @var{opt}. @code{@var{opt} = \"a\"} indicates that all\n\ eigenvalues with negative real parts should be moved to the leading\n\ -block of\n\ -@tex\n\ -$S$\n\ -@end tex\n\ -@ifnottex\n\ -@var{S}\n\ -@end ifnottex\n\ +block of @var{S}\n\ (used in @code{are}), @code{@var{opt} = \"d\"} indicates that all eigenvalues\n\ -with magnitude less than one should be moved to the leading block of\n\ -@tex\n\ -$S$\n\ -@end tex\n\ -@ifnottex\n\ -@var{S}\n\ -@end ifnottex\n\ +with magnitude less than one should be moved to the leading block of @var{S}\n\ (used in @code{dare}), and @code{@var{opt} = \"u\"}, the default, indicates\n\ -that no ordering of eigenvalues should occur. The leading\n\ -@tex\n\ -$k$\n\ -@end tex\n\ -@ifnottex\n\ -@var{k}\n\ -@end ifnottex\n\ -columns of\n\ -@tex\n\ -$U$\n\ -@end tex\n\ -@ifnottex\n\ -@var{U}\n\ -@end ifnottex\n\ -always span the\n\ -@tex\n\ -$A$-invariant\n\ -@end tex\n\ -@ifnottex\n\ -@var{A}-invariant\n\ -@end ifnottex\n\ -subspace corresponding to the\n\ -@tex\n\ -$k$\n\ -@end tex\n\ -@ifnottex\n\ -@var{k}\n\ -@end ifnottex\n\ -leading eigenvalues of\n\ -@tex\n\ -$S$.\n\ -@end tex\n\ -@ifnottex\n\ -@var{S}.\n\ -@end ifnottex\n\ +that no ordering of eigenvalues should occur. The leading @var{k}\n\ +columns of @var{U} always span the @var{A}-invariant\n\ +subspace corresponding to the @var{k} leading eigenvalues of @var{S}.\n\ +\n\ +The Schur@tie{}decomposition is used to compute eigenvalues of a\n\ +square matrix, and has applications in the solution of algebraic\n\ +Riccati equations in control (see @code{are} and @code{dare}).\n\ +@seealso{rsf2csf}\n\ @end deftypefn") { octave_value_list retval; @@ -398,8 +295,14 @@ \n\ Note that the following relations hold: \n\ \n\ +@tex\n\ +$UR \\cdot TR \\cdot {UR}^T = U T U^{\\dagger}$ and\n\ +$U^{\\dagger} U$ is the identity matrix I.\n\ +@end tex\n\ +@ifnottex\n\ @code{@var{UR} * @var{TR} * @var{UR}' = @var{U} * @var{T} * @var{U}'} and\n\ @code{@var{U}' * @var{U}} is the identity matrix I.\n\ +@end ifnottex\n\ \n\ Note also that @var{U} and @var{T} are not unique.\n\ @seealso{schur}\n\
--- a/src/DLD-FUNCTIONS/sqrtm.cc +++ b/src/DLD-FUNCTIONS/sqrtm.cc @@ -214,7 +214,8 @@ DEFUN_DLD (sqrtm, args, nargout, "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {[@var{result}, @var{error_estimate}] =} sqrtm (@var{A})\n\ +@deftypefn {Loadable Function} {@var{s} =} sqrtm (@var{A})\n\ +@deftypefnx {Loadable Function} {[@var{s}, @var{error_estimate}] =} sqrtm (@var{A})\n\ Compute the matrix square root of the square matrix @var{A}.\n\ \n\ Ref: N.J. Higham. @cite{A New sqrtm for @sc{matlab}}. Numerical\n\
--- a/src/DLD-FUNCTIONS/svd.cc +++ b/src/DLD-FUNCTIONS/svd.cc @@ -48,7 +48,7 @@ Compute the singular value decomposition of @var{A}\n\ @tex\n\ $$\n\ - A = U S V^H\n\ + A = U S V^{\\dagger}\n\ $$\n\ @end tex\n\ @ifnottex\n\ @@ -406,8 +406,9 @@ DEFUN_DLD (svd_driver, args, nargout, "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {@var{old} =} svd_driver (@var{new})\n\ -Set or query the underlying @sc{lapack} driver used by @code{svd}.\n\ +@deftypefn {Loadable Function} {@var{val} =} svd_driver ()\n\ +@deftypefnx {Loadable Function} {@var{old_val} =} svd_driver (@var{new_val})\n\ +Query or set the underlying @sc{lapack} driver used by @code{svd}.\n\ Currently recognized values are \"gesvd\" and \"gesdd\". The default\n\ is \"gesvd\".\n\ @seealso{svd}\n\
--- a/src/data.cc +++ b/src/data.cc @@ -4682,51 +4682,51 @@ DEFUN (norm, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} norm (@var{a})\n\ -@deftypefnx {Built-in Function} {} norm (@var{a}, @var{p})\n\ -@deftypefnx {Built-in Function} {} norm (@var{a}, @var{p}, @var{opt})\n\ -Compute the p-norm of the matrix @var{a}. If the second argument is\n\ +@deftypefn {Built-in Function} {} norm (@var{A})\n\ +@deftypefnx {Built-in Function} {} norm (@var{A}, @var{p})\n\ +@deftypefnx {Built-in Function} {} norm (@var{A}, @var{p}, @var{opt})\n\ +Compute the p-norm of the matrix @var{A}. If the second argument is\n\ missing, @code{p = 2} is assumed.\n\ \n\ -If @var{a} is a matrix (or sparse matrix):\n\ +If @var{A} is a matrix (or sparse matrix):\n\ \n\ @table @asis\n\ @item @var{p} = @code{1}\n\ -1-norm, the largest column sum of the absolute values of @var{a}.\n\ +1-norm, the largest column sum of the absolute values of @var{A}.\n\ \n\ @item @var{p} = @code{2}\n\ -Largest singular value of @var{a}.\n\ +Largest singular value of @var{A}.\n\ \n\ @item @var{p} = @code{Inf} or @code{\"inf\"}\n\ @cindex infinity norm\n\ -Infinity norm, the largest row sum of the absolute values of @var{a}.\n\ +Infinity norm, the largest row sum of the absolute values of @var{A}.\n\ \n\ @item @var{p} = @code{\"fro\"}\n\ @cindex Frobenius norm\n\ -Frobenius norm of @var{a}, @code{sqrt (sum (diag (@var{a}' * @var{a})))}.\n\ +Frobenius norm of @var{A}, @code{sqrt (sum (diag (@var{A}' * @var{A})))}.\n\ \n\ @item other @var{p}, @code{@var{p} > 1}\n\ @cindex general p-norm \n\ maximum @code{norm (A*x, p)} such that @code{norm (x, p) == 1}\n\ @end table\n\ \n\ -If @var{a} is a vector or a scalar:\n\ +If @var{A} is a vector or a scalar:\n\ \n\ @table @asis\n\ @item @var{p} = @code{Inf} or @code{\"inf\"}\n\ -@code{max (abs (@var{a}))}.\n\ +@code{max (abs (@var{A}))}.\n\ \n\ @item @var{p} = @code{-Inf}\n\ -@code{min (abs (@var{a}))}.\n\ +@code{min (abs (@var{A}))}.\n\ \n\ @item @var{p} = @code{\"fro\"}\n\ -Frobenius norm of @var{a}, @code{sqrt (sumsq (abs (a)))}.\n\ +Frobenius norm of @var{A}, @code{sqrt (sumsq (abs (A)))}.\n\ \n\ @item @var{p} = 0\n\ Hamming norm - the number of nonzero elements.\n\ \n\ @item other @var{p}, @code{@var{p} > 1}\n\ -p-norm of @var{a}, @code{(sum (abs (@var{a}) .^ @var{p})) ^ (1/@var{p})}.\n\ +p-norm of @var{A}, @code{(sum (abs (@var{A}) .^ @var{p})) ^ (1/@var{p})}.\n\ \n\ @item other @var{p} @code{@var{p} < 1}\n\ the p-pseudonorm defined as above.\n\