This is Info file octave.info, produced by Makeinfo-1.64 from the input file octave.texi. Copyright (C) 1993, 1994, 1995 John W. Eaton. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.  File: octave.info, Node: User Preferences, Next: Other Built-in Variables, Prev: Predefined Constants, Up: Built-in Variables User Preferences ================ This section describes the variables that you can use to customize Octave's behavior. Normally, preferences are set in the file `~/.octaverc', so that you can customize your environment in the same way each time you use Octave without having to remember and retype all the necessary commands. *Note Startup Files:: for more information. `EDITOR' A string naming the editor to use with the `edit_history' command. If the environment variable `EDITOR' is set when Octave starts, its value is used as the default. Otherwise, `EDITOR' is set to `"vi"'. `IMAGEPATH' A colon separated list of directories in which to search for image files. *Note Image Processing:: for a description of Octave's image processing capabilities. `INFO_FILE' A string naming the location of the Octave info file. The default value is `"/ade/info/octave.info"'. `LOADPATH' A colon separated list of directories in which to search for function files. *Note Functions and Scripts::. The value of `LOADPATH' overrides the environment variable `OCTAVE_PATH'. *Note Installation::. `LOADPATH' is now handled in the same way as TeX handles `TEXINPUTS'. If the path starts with `:', the standard path is prepended to the value of `LOADPATH'. If it ends with `:' the standard path is appended to the value of `LOADPATH'. In addition, if any path element ends in `//', that directory and all subdirectories it contains are searched recursively for function files. This can result in a slight delay as Octave caches the lists of files found in the `LOADPATH' the first time Octave searches for a function. After that, searching is usually much faster because Octave normally only needs to search its internal cache for files. To improve performance of recursive directory searching, it is best for each directory that is to be searched recursively to contain *either* additional subdirectories *or* function files, but not a mixture of both. *Note Organization of Functions:: for a description of the function file directories that are distributed with Octave. `OCTAVE_VERSION' The version number of Octave, as a string. `PAGER' The default value is `"less"', or, if `less' is not available on your system, `"more"'. *Note Installation::, and *Note Input and Output::. `PS1' The primary prompt string. When executing interactively, Octave displays the primary prompt `PS1' when it is ready to read a command. Octave allows the prompt to be customized by inserting a number of backslash-escaped special characters that are decoded as follows: `\t' The time. `\d' The date. `\n' Begins a new line by printing the equivalent of a carriage return followed by a line feed. `\s' The name of the program (usually just `octave'). `\w' The current working directory. `\W' The basename of the current working directory. `\u' The username of the current user. `\h' The hostname. `\#' The command number of this command, counting from when Octave starts. `\!' The history number of this command. This differs from `\#' by the number of commands in the history list when Octave starts. `\$' If the effective UID is 0, a #, otherwise a $. `\nnn' The character whose character code in octal is `nnn'. `\\' A backslash. The default value of `PS1' is `"\s:\#> "'. To change it, use a command like octave:13> PS1 = "\\u@\\h> " which will result in the prompt `boris@kremvax> ' for the user `boris' logged in on the host `kremvax'. Note that two backslashes are required to enter a backslash into a string. *Note String Constants::. `PS2' The secondary prompt string, which is printed when Octave is expecting additional input to complete a command. For example, when defining a function over several lines, Octave will print the value of `PS1' at the beginning of each line after the first. Octave allows `PS2' to be customized in the same way as `PS1'. The default value of `PS2' is `"> "'. `PS4' If Octave is invoked with the `--echo-input' option, the value of `PS4' is printed before each line of input that is echoed. Octave allows `PS4' to be customized in the same way as `PS1'. The default value of `PS4' is `"+ "'. *Note Invoking Octave::, for a description of `--echo-input'. `automatic_replot' If this variable is `"true"', Octave will automatically send a `replot' command to `gnuplot' each time the plot changes. Since this is fairly inefficient, the default value is `"false"'. `default_return_value' The value given to otherwise unitialized return values if `define_all_return_values' is `"true"'. The default value is `[]'. `default_save_format' Specify the default format used by the `save' command. Options are `"ascii"', `"binary"', `"mat-binary"', or `"float-binary"'. The default value is `ascii'. `define_all_return_values' If the value of `define_all_return_values' is `"true"', Octave will substitute the value specified by `default_return_value' for any return values that remain undefined when a function returns. The default value is `"false"'. `do_fortran_indexing' If the value of `do_fortran_indexing' is `"true"', Octave allows you to select elements of a two-dimensional matrix using a single index by treating the matrix as a single vector created from the columns of the matrix. The default value is `"false"'. `empty_list_elements_ok' This variable controls whether Octave ignores empty matrices in a matrix list. For example, if the value of `empty_list_elements_ok' is `"true"', Octave will ignore the empty matrices in the expression a = [1, [], 3, [], 5] and the variable `a' will be assigned the value `[ 1 3 5 ]'. The default value is `"warn"'. `gnuplot_binary' The name of the program invoked by the plot command. The default value is `"gnuplot"'. *Note Installation::. `ignore_function_time_stamp' This variable variable can be used to prevent Octave from making the system call `stat()' each time it looks up functions defined in function files. If `ignore_function_time_stamp' to `"system"', Octave will not automatically recompile function files in subdirectories of `/ade/lib/1.1.1' if they have changed since they were last compiled, but will recompile other function files in the `LOADPATH' if they change. If set to `"all"', Octave will not recompile any function files unless their definitions are removed with `clear'. For any other value of `ignore_function_time_stamp', Octave will always check to see if functions defined in function files need to recompiled. The default value of `ignore_function_time_stamp' is `"system"'. `implicit_str_to_num_ok' If the value of `implicit_str_to_num_ok' is `"true"', implicit conversions of strings to their numeric ASCII equivalents are allowed. Otherwise, an error message is printed and control is returned to the top level. The default value is `"false"'. `ok_to_lose_imaginary_part' If the value of `ok_to_lose_imaginary_part' is `"true"', implicit conversions of complex numbers to real numbers are allowed (for example, by fsolve). If the value is `"warn"', the conversion is allowed, but a warning is printed. Otherwise, an error message is printed and control is returned to the top level. The default value is `"warn"'. `output_max_field_width' This variable specifies the maximum width of a numeric output field. The default value is 10. It is possible to achieve a wide range of output styles by using different values of `output_precision' and `output_max_field_width'. Reasonable combinations can be set using the `format' function. *Note Basic Input and Output::. `output_precision' This variable specifies the minimum number of significant figures to display for numeric output. The default value is 5. It is possible to achieve a wide range of output styles by using different values of `output_precision' and `output_max_field_width'. Reasonable combinations can be set using the `format' function. *Note Basic Input and Output::. `page_screen_output' If the value of `page_screen_output' is `"true"', all output intended for the screen that is longer than one page is sent through a pager. This allows you to view one screenful at a time. Some pagers (such as `less'--see *Note Installation::) are also capable of moving backward on the output. The default value is `"true"'. *Note Input and Output::. You can choose the program to use as the pager by setting the variable `PAGER'. `prefer_column_vectors' If `prefer_column_vectors' is `"true"', operations like for i = 1:10 a (i) = i; endfor (for `a' previously undefined) produce column vectors. Otherwise, row vectors are preferred. The default value is `"false"'. If a variable is already defined to be a vector (a matrix with a single row or column), the original orientation is respected, regardless of the value of `prefer_column_vectors'. `prefer_zero_one_indexing' If the value of `prefer_zero_one_indexing' is `"true"', Octave will perform zero-one style indexing when there is a conflict with the normal indexing rules. *Note Index Expressions::. For example, given a matrix a = [1, 2, 3, 4] with `prefer_zero_one_indexing' is set to `"true"', the expression a ([1, 1, 1, 1]) results in the matrix `[ 1 2 3 4 ]'. If the value of `prefer_zero_one_indexing' set to `"false"', the result would be the matrix `[ 1 1 1 1 ]'. In the first case, Octave is selecting each element corresponding to a `1' in the index vector. In the second, Octave is selecting the first element multiple times. The default value for `prefer_zero_one_indexing' is `"false"'. `print_answer_id_name' If the value of `print_answer_id_name' is `"true"', variable names are printed along with the result. Otherwise, only the result values are printed. The default value is `"true"'. `print_empty_dimensions' If the value of `print_empty_dimensions' is `"true"', the dimensions of empty matrices are printed along with the empty matrix symbol, `[]'. For example, the expression zeros (3, 0) will print ans = [](3x0) `propagate_empty_matrices' If the value of `propagate_empty_matrices' is `"true"', functions like `inverse' and `svd' will return an empty matrix if they are given one as an argument. The default value is `"true"'. *Note Empty Matrices::. `resize_on_range_error' If the value of `resize_on_range_error' is `"true"', expressions like for i = 1:10 a (i) = i; endfor (for `a' previously undefined) result in the variable `a' being resized to be just large enough to hold the new value. Otherwise uninitialized elements are set to zero. If the value of `resize_on_range_error' is `"false"', an error message is printed and control is returned to the top level. The default value is `"true"'. `return_last_computed_value' If the value of `return_last_computed_value' is true, and a function is defined without explicitly specifying a return value, the function will return the value of the last expression. Otherwise, no value will be returned. The default value is `"false"'. For example, the function function f () 2 + 2; endfunction will either return nothing, if `return_last_computed_value' is `"false"', or 4, if it is `"true"'. `save_precision' This variable specifies the number of digits to keep when saving data with the `save' command. The default value is 17. `silent_functions' If the value of `silent_functions' is `"true"', internal output from a function is suppressed. Otherwise, the results of expressions within a function body that are not terminated with a semicolon will have their values printed. The default value is `"false"'. For example, if the function function f () 2 + 2 endfunction is executed, Octave will either print `ans = 4' or nothing depending on the value of `silent_functions'. `split_long_rows' For large matrices, Octave may not be able to display all the columns of a given row on one line of your screen. This can result in missing information or output that is nearly impossible to decipher, depending on whether your terminal truncates or wraps long lines. If the value of `split_long_rows' is `"true"', Octave will display the matrix in a series of smaller pieces, each of which can fit within the limits of your terminal width. Each set of rows is labeled so that you can easily see which columns are currently being displayed. For example: octave:13> rand (2, 9) ans = Columns 1 through 7: 0.92205 0.72628 0.99841 0.62590 0.82422 0.77486 0.30258 0.15999 0.79484 0.75443 0.86995 0.91430 0.23980 0.64591 Columns 8 and 9: 0.08894 0.13266 0.28008 0.65575 The default value of `split_long_rows' is `"true"'. `suppress_verbose_help_message' If the value of `suppress_verbose_help_message' is `"true"', Octave will not add additional help information to the end of the output from the `help' command and usage messages for built-in commands. `treat_neg_dim_as_zero' If the value of `treat_neg_dim_as_zero' is `"true"', expressions like eye (-1) produce an empty matrix (i.e., row and column dimensions are zero). Otherwise, an error message is printed and control is returned to the top level. The default value is `"false"'. `warn_assign_as_truth_value' If the value of `warn_assign_as_truth_value' is `"true"', a warning is issued for statements like if (s = t) ... since such statements are not common, and it is likely that the intent was to write if (s == t) ... instead. There are times when it is useful to write code that contains assignments within the condition of a `while' or `if' statement. For example, statements like while (c = getc()) ... are common in C programming. It is possible to avoid all warnings about such statements by setting `warn_assign_as_truth_value' to `"false"', but that may also let real errors like if (x = 1) # intended to test (x == 1)! ... slip by. In such cases, it is possible suppress errors for specific statements by writing them with an extra set of parentheses. For example, writing the previous example as while ((c = getc())) ... will prevent the warning from being printed for this statement, while allowing Octave to warn about other assignments used in conditional contexts. The default value of `warn_assign_as_truth_value' is `"true"'. `warn_comma_in_global_decl' If the value of `warn_comma_in_global_decl' is `"true"', a warning is issued for statements like global a = 1, b which makes the variables `a' and `b' global and assigns the value 1 to the variable `a', because in this context, the comma is not interpreted as a statement separator. The default value of `warn_comma_in_global_decl' is `"true"'. `warn_divide_by_zero' If the value of `warn_divide_by_zero' is `"true"', a warning is issued when Octave encounters a division by zero. If the value is `"false"', the warning is omitted. The default value is `"true"'. `warn_function_name_clash' If the value of `warn_function_name_clash' is `"true"', a warning is issued when Octave finds that the name of a function defined in a function file differs from the name of the file. If the value is `"false"', the warning is omitted. The default value is `"true"'. `whitespace_in_literal_matrix' This variable allows some control over how Octave decides to convert spaces to commas and semicolons in matrix expressions like `[m (1)]' or [ 1, 2, 3, 4 ] If the value of `whitespace_in_literal_matrix' is `"ignore"', Octave will never insert a comma or a semicolon in a literal matrix list. For example, the expression `[1 2]' will result in an error instead of being treated the same as `[1, 2]', and the expression [ 1, 2, 3, 4 ] will result in the vector [1 2 3 4] instead of a matrix. If the value of `whitespace_in_literal_matrix' is `"traditional"', Octave will convert spaces to a comma between identifiers and `('. For example, given the matrix m = [3 2] the expression [m (1)] will be parsed as [m, (1)] and will result in [3 2 1] and the expression [ 1, 2, 3, 4 ] will result in a matrix because the newline character is converted to a semicolon (row separator) even though there is a comma at the end of the first line (trailing commas or semicolons are ignored). This is apparently how MATLAB behaves. Any other value for `whitespace_in_literal_matrix' results in behavior that is the same as traditional, except that Octave does not convert spaces to a comma between identifiers and `('. For example, the expression [m (1)] will produce `3'. This is the way Octave has always behaved.  File: octave.info, Node: Other Built-in Variables, Next: Summary of Preference Variables, Prev: User Preferences, Up: Built-in Variables Other Built-in Variables ======================== In addition to these variables, there are two other special built-in variables whose values are automatically updated. `ans' This variable holds the most recently computed result that was not explicitly assigned to a variable. For example, after the expression 3^2 + 4^2 is evaluated, the value of `ans' is `25'. `PWD' The current working directory. The value of `PWD' is updated each time the current working directory is changed with the `cd' command. *Note System Utilities::.  File: octave.info, Node: Summary of Preference Variables, Prev: Other Built-in Variables, Up: Built-in Variables Summary of Preference Variables =============================== Here is a summary of all of Octave's preference variables and their default values. In the following table `OCTAVE_HOME' stands for the root directory where Octave is installed, and `VERSION' stands for the Octave version number. EDITOR EDITOR environment variable, or "vi" INFO_FILE "OCTAVE_HOME/info/octave.info" LOADPATH OCTAVE_PATH environment variable, or ".:OCTAVE_HOME/lib/VERSION" PAGER "less", or "more" PS1 "\s:\#> " PS2 "> " PS4 "+ " automatic_replot "false" default_return_value [] do_fortran_indexing "false" define_all_return_values "false" empty_list_elements_ok "warn" gnuplot_binary "gnuplot" ignore_function_time_stamp "system" implicit_str_to_num_ok "false" ok_to_lose_imaginary_part "warn" output_max_field_width 10 output_precision 5 page_screen_output "true" prefer_column_vectors "false" prefer_zero_one_indexing "false" print_answer_id_name "true" print_empty_dimensions "true" resize_on_range_error "true" return_last_computed_value "false" save_precision 17 silent_functions "false" split_long_rows "true" suppress_verbose_help_message "true" treat_neg_dim_as_zero "false" warn_assign_as_truth_value "true" warn_comma_in_global_decl "true" warn_divide_by_zero "true" warn_function_name_clash "true" whitespace_in_literal_matrix ""  File: octave.info, Node: Arithmetic, Next: Linear Algebra, Prev: Built-in Variables, Up: Top Arithmetic ********** Unless otherwise noted, all of the functions described in this chapter will work for real and complex scalar or matrix arguments. * Menu: * Utility Functions:: * Complex Arithmetic:: * Trigonometry:: * Sums and Products:: * Special Functions::  File: octave.info, Node: Utility Functions, Next: Complex Arithmetic, Prev: Arithmetic, Up: Arithmetic Utility Functions ================= The following functions are available for working with complex numbers. Each expects a single argument, and given a matrix, they work on an element by element basis. `ceil (X)' Return the smallest integer not less than X. If X is complex, return `ceil (real (X)) + ceil (imag (X)) * I'. `floor (X)' Return the largest integer not greater than X. If X is complex, return `floor (real (X)) + floor (imag (X)) * I'. `fix (X)' Truncate X toward zero. If X is complex, return `fix (real (X)) + fix (imag (X)) * I'. `round (X)' Return the integer nearest to X. If X is complex, return `round (real (X)) + round (imag (X)) * I'. `sign (X)' Compute the "signum" function, which is defined as -1, x < 0; sign (x) = 0, x = 0; 1, x > 0. For complex arguments, `sign' returns `x ./ abs (X)'. `exp (X)' Compute the exponential of X. To compute the matrix exponential, see *Note Linear Algebra::. `gcd (X, `...')' Compute the greatest common divisor of the elements of X, or the list of all the arguments. For example, gcd (a1, ..., ak) is the same as gcd ([a1, ..., ak]) An optional second return value, V contains an integer vector such that g = v(1) * a(k) + ... + v(k) * a(k) `lcm (X, `...')' Compute the least common multiple of the elements elements of X, or the list of all the arguments. For example, lcm (a1, ..., ak) is the same as lcm ([a1, ..., ak]). `log (X)' Compute the natural logarithm of X. To compute the matrix logarithm, see *Note Linear Algebra::. `log2 (X)' Compute the base-2 logarithm of X. `log10 (X)' Compute the base-10 logarithm of X. `sqrt (X)' Compute the square root of X. To compute the matrix square root, see *Note Linear Algebra::. `max (X)' For a vector argument, return the maximum value. For a matrix argument, return the maximum value from each column, as a row vector. Thus, max (max (X)) returns the largest element of X. For complex arguments, the magnitude of the elements are used for comparison. `min (X)' Like `max', but return the minimum value. `rem (X, Y)' Return the remainder of `X / Y', computed using the expression x - y .* fix (x ./ y) An error message is printed if the dimensions of the arguments do not agree, or if either of the arguments is complex.  File: octave.info, Node: Complex Arithmetic, Next: Trigonometry, Prev: Utility Functions, Up: Arithmetic Complex Arithmetic ================== The following functions are available for working with complex numbers. Each expects a single argument. Given a matrix they work on an element by element basis. `abs (X)' Compute the magnitude of X. `angle (X)' `arg (X)' Compute the argument of X. `conj (X)' Return the complex conjugate of X. `imag (X)' Return the imaginary part of X. `real (X)' Return the real part of X.  File: octave.info, Node: Trigonometry, Next: Sums and Products, Prev: Complex Arithmetic, Up: Arithmetic Trigonometry ============ Octave provides the following trigonometric functions: sin asin sinh asinh cos acos cosh acosh tan atan tanh atanh sec asec sech asech csc acsc csch acsch cot acot coth acoth Each of these functions expect a single argument. For matrix arguments, they work on an element by element basis. For example, the expression sin ([1, 2; 3, 4]) produces ans = 0.84147 0.90930 0.14112 -0.75680 `atan2 (Y, X)'  File: octave.info, Node: Sums and Products, Next: Special Functions, Prev: Trigonometry, Up: Arithmetic Sums and Products ================= `sum (X)' For a vector argument, return the sum of all the elements. For a matrix argument, return the sum of the elements in each column, as a row vector. The sum of an empty matrix is 0 if it has no columns, or a vector of zeros if it has no rows (*note Empty Matrices::.). `prod (X)' For a vector argument, return the product of all the elements. For a matrix argument, return the product of the elements in each column, as a row vector. The product of an empty matrix is 1 if it has no columns, or a vector of ones if it has no rows (*note Empty Matrices::.). `cumsum (X)' Return the cumulative sum of each column of X. For example, cumsum ([1, 2; 3, 4]) produces ans = 1 2 4 6 `cumprod (X)' Return the cumulative product of each column of X. For example, cumprod ([1, 2; 3, 4]) produces ans = 1 2 3 8 `sumsq (X)' For a vector argument, return the sum of the squares of all the elements. For a matrix argument, return the sum of the squares of the elements in each column, as a row vector.  File: octave.info, Node: Special Functions, Prev: Sums and Products, Up: Arithmetic Special Functions ================= `beta' Returns the beta function, beta (a, b) = gamma (a) * gamma (b) / gamma (a + b). `betai (A, B, X)' Returns the incomplete beta function, x / betai (a, b, x) = beta (a, b)^(-1) | t^(a-1) (1-t)^(b-1) dt. / t=0 If x has more than one component, both A and B must be scalars. If X is a scalar, A and B must be of compatible dimensions. `erf' Computes the error function, z / erf (z) = (2/sqrt (pi)) | e^(-t^2) dt / t=0 `erfc (Z)' Computes the complementary error function, `1 - erf (Z)'. `erfinv' Computes the inverse of the error function. `gamma (Z)' Computes the gamma function, infinity / gamma (z) = | t^(z-1) exp (-t) dt. / t=0 `gammai (A, X)' Computes the incomplete gamma function, x 1 / gammai (a, x) = --------- | exp (-t) t^(a-1) dt gamma (a) / t=0 If A is scalar, then `gammai (A, X)' is returned for each element of X and vice versa. If neither A nor X is scalar, the sizes of A and X must agree, and GAMMAI is applied element-by-element. `lgamma' Returns the natural logarithm of the gamma function.  File: octave.info, Node: Linear Algebra, Next: Polynomial Manipulations, Prev: Arithmetic, Up: Top Linear Algebra ************** This chapter documents the linear algebra functions of Octave. Reference material for many of these options may be found in Golub and Van Loan, `Matrix Computations, 2nd Ed.', Johns Hopkins, 1989, and in `LAPACK Users' Guide', SIAM, 1992. * Menu: * Basic Matrix Functions:: * Matrix Factorizations:: * Functions of a Matrix::  File: octave.info, Node: Basic Matrix Functions, Next: Matrix Factorizations, Prev: Linear Algebra, Up: Linear Algebra Basic Matrix Functions ====================== `balance' aa = balance (a, opt) [dd, aa] = balance(a, opt) [dd, aa] = balance (a, opt) [cc, dd, aa, bb] = balance (a, b, opt) `[dd, aa] = balance (a)' returns `aa = dd \ a * dd'. `aa' is a matrix whose row/column norms are roughly equal in magnitude, and `dd' = `p * d', where `p' is a permutation matrix and `d' is a diagonal matrix of powers of two. This allows the equilibration to be computed without roundoff. Results of eigenvalue calculation are typically improved by balancing first. `[cc, dd, aa, bb] = balance (a, b)' returns `aa' (`bb') `= cc*a*dd (cc*b*dd)'), where `aa' and `bb' have non-zero elements of approximately the same magnitude and `cc' and `dd' are permuted diagonal matrices as in `dd' for the algebraic eigenvalue problem. The eigenvalue balancing option `opt' is selected as follows: `"N"', `"n"' No balancing; arguments copied, transformation(s) set to identity. `"P"', `"p"' Permute argument(s) to isolate eigenvalues where possible. `"S"', `"s"' Scale to improve accuracy of computed eigenvalues. `"B"', `"b"' Permute and scale, in that order. Rows/columns of a (and b) that are isolated by permutation are not scaled. This is the default behavior. Algebraic eigenvalue balancing uses standard LAPACK routines. Generalized eigenvalue problem balancing uses Ward's algorithm (SIAM Journal on Scientific and Statistical Computing, 1981). `cond (A)' Compute the (two-norm) condition number of a matrix. `cond (a)' is defined as `norm (a) * norm (inv (a))', and is computed via a singular value decomposition. `det (A)' Compute the determinant of A using LINPACK. `eig' = eig (a) [v, lambda] = eig (a) The eigenvalues (and eigenvectors) of a matrix are computed in a several step process which begins with a Hessenberg decomposition (see `hess'), followed by a Schur decomposition (see `schur'), from which the eigenvalues are apparent. The eigenvectors, when desired, are computed by further manipulations of the Schur decomposition. See also: `hess', `schur'. `givens' [c, s] = givens (x, y) G = givens (x, y) `G = givens(x, y)' returns a 2 x 2 orthogonal matrix `G = [c s; -s' c]' such that `G [x; y] = [*; 0]' (x, y scalars) `inv (A)' `inverse (A)' Compute the inverse of the square matrix A. `norm (A, P)' Compute the p-norm of the matrix A. If the second argument is missing, `p = 2' is assumed. If A is a matrix: P = `1' 1-norm, the largest column sum of A. P = `2' Largest singular value of A. P = `Inf' Infinity norm, the largest row sum of A. P = `"fro"' Frobenius norm of A, `sqrt (sum (diag (a' * a)))'. If A is a vector or a scalar: P = `Inf' `max (abs (a))'. P = `-Inf' `min (abs (a))'. other p-norm of A, `(sum (abs (a) .^ p)) ^ (1/p)'. `null (A, TOL)' Returns an orthonormal basis of the null space of A. The dimension of the null space is taken as the number of singular values of A not greater than TOL. If the argument TOL is missing, it is computed as max (size (a)) * max (svd (a)) * eps `orth (A, TOL)' Returns an orthonormal basis of the range of A. The dimension of the range space is taken as the number of singular values of A greater than TOL. If the argument TOL is missing, it is computed as max (size (a)) * max (svd (a)) * eps `pinv (X, TOL)' Returns the pseudoinverse of X. Singular values less than TOL are ignored. If the second argument is omitted, it is assumed that tol = max (size (X)) * sigma_max (X) * eps, where `sigma_max (X)' is the maximal singular value of X. `rank (A, TOL)' Compute the rank of A, using the singular value decomposition. The rank is taken to be the number of singular values of A that are greater than the specified tolerance TOL. If the second argument is omitted, it is taken to be tol = max (size (a)) * sigma (1) * eps; where `eps' is machine precision and `sigma' is the largest singular value of `a'. `trace (A)' Compute the trace of A, `sum (diag (a))'.  File: octave.info, Node: Matrix Factorizations, Next: Functions of a Matrix, Prev: Basic Matrix Functions, Up: Linear Algebra Matrix Factorizations ===================== `chol (A)' Compute the Cholesky factor, R, of the symmetric positive definite matrix A, where r' * r = a. `hess (A)' Compute the Hessenberg decomposition of the matrix A. h = hess (a) [p, h] = hess (a) The Hessenberg decomposition is usually used as the first step in an eigenvalue computation, but has other applications as well (see Golub, Nash, and Van Loan, IEEE Transactions on Automatic Control, 1979. The Hessenberg decomposition is `p * h * p' = a' where `p' is a square unitary matrix (`p' * p = I', using complex-conjugate transposition) and `h' is upper Hessenberg (`i >= j+1 => h (i, j) = 0'). `lu (A)' Compute the LU decomposition of A, using subroutines from LAPACK. The result is returned in a permuted form, according to the optional return value P. For example, given the matrix `a = [1, 2; 3, 4]', [l, u, p] = lu (a) returns l = 1.00000 0.00000 0.33333 1.00000 u = 3.00000 4.00000 0.00000 0.66667 p = 0 1 1 0 `qr (A)' Compute the QR factorization of A, using standard LAPACK subroutines. For example, given the matrix `a = [1, 2; 3, 4]', [q, r] = qr (a) returns q = -0.31623 -0.94868 -0.94868 0.31623 r = -3.16228 -4.42719 0.00000 -0.63246 The `qr' factorization has applications in the solution of least squares problems `min norm(A x - b)' for overdetermined systems of equations (i.e., `a' is a tall, thin matrix). The `qr' factorization is `q * r = a' where `q' is an orthogonal matrix and `r' is upper triangular. The permuted `qr' factorization `[q, r, pi] = qr (a)' forms the `qr' factorization such that the diagonal entries of `r' are decreasing in magnitude order. For example, given the matrix `a = [1, 2; 3, 4]', [q, r, pi] = qr(a) returns q = -0.44721 -0.89443 -0.89443 0.44721 r = -4.47214 -3.13050 0.00000 0.44721 p = 0 1 1 0 The permuted `qr' factorization `[q, r, pi] = qr (a)' factorization allows the construction of an orthogonal basis of `span (a)'. `schur' [u, s] = schur (a, opt) opt = "a", "d", or "u" s = schur (a) The Schur decomposition is used to compute eigenvalues of a square matrix, and has applications in the solution of algebraic Riccati equations in control (see `are' and `dare'). `schur' always returns `s = u' * a * u' where `u' is a unitary matrix (`u'* u' is identity) and `s' is upper triangular. The eigenvalues of `a' (and `s') are the diagonal elements of `s' If the matrix `a' is real, then the real Schur decomposition is computed, in which the matrix `u' is orthogonal and `s' is block upper triangular with blocks of size at most `2 x 2' blocks along the diagonal. The diagonal elements of `s' (or the eigenvalues of the `2 x 2' blocks, when appropriate) are the eigenvalues of `a' and `s'. The eigenvalues are optionally ordered along the diagonal according to the value of `opt'. `opt = "a"' indicates that all eigenvalues with negative real parts should be moved to the leading block of `s' (used in `are'), `opt = "d"' indicates that all eigenvalues with magnitude less than one should be moved to the leading block of `s' (used in `dare'), and `opt = "u"', the default, indicates that no ordering of eigenvalues should occur. The leading `k' columns of `u' always span the `a'-invariant subspace corresponding to the `k' leading eigenvalues of `s'. `svd (A)' Compute the singular value decomposition of A a = u * sigma * v' The function `svd' normally returns the vector of singular values. If asked for three return values, it computes U, S, and V. For example, svd (hilb (3)) returns ans = 1.4083189 0.1223271 0.0026873 and [u, s, v] = svd (hilb (3)) returns u = -0.82704 0.54745 0.12766 -0.45986 -0.52829 -0.71375 -0.32330 -0.64901 0.68867 s = 1.40832 0.00000 0.00000 0.00000 0.12233 0.00000 0.00000 0.00000 0.00269 v = -0.82704 0.54745 0.12766 -0.45986 -0.52829 -0.71375 -0.32330 -0.64901 0.68867 If given a second argument, `svd' returns an economy-sized decomposition, eliminating the unnecessary rows or columns of U or V.  File: octave.info, Node: Functions of a Matrix, Prev: Matrix Factorizations, Up: Linear Algebra Functions of a Matrix ===================== `expm' expm (a) Returns the exponential of a matrix, defined as the infinite Taylor series expm(a) = I + a + a^2/2! + a^3/3! + ... The Taylor series is *not* the way to compute the matrix exponential; see Moler and Van Loan, `Nineteen Dubious Ways to Compute the Exponential of a Matrix', SIAM Review, 1978. This routine uses Ward's diagonal Pade' approximation method with three step preconditioning (SIAM Journal on Numerical Analysis, 1977). Diagonal Pade' approximations are rational polynomials of matrices -1 D (a) N (a) whose Taylor series matches the first `2q+1' terms of the Taylor series above; direct evaluation of the Taylor series (with the same preconditioning steps) may be desirable in lieu of the Pade' approximation when `Dq(a)' is ill-conditioned. `logm (A)' Compute the matrix logarithm of the square matrix A. Note that this is currently implemented in terms of an eigenvalue expansion and needs to be improved to be more robust. `sqrtm (A)' Compute the matrix square root of the square matrix A. Note that this is currently implemented in terms of an eigenvalue expansion and needs to be improved to be more robust. `kron (A, B)' Form the kronecker product of two matrices, defined block by block as x = [a(i, j) b] `qzhess (A, B)' Compute the Hessenberg-triangular decomposition of the matrix pencil `(a, b)'. This function returns `aa = q * a * z', `bb = q * b * z', `q', `z' orthogonal. For example, [aa, bb, q, z] = qzhess (a, b) The Hessenberg-triangular decomposition is the first step in Moler and Stewart's QZ decomposition algorithm. (The QZ decomposition will be included in a later release of Octave.) Algorithm taken from Golub and Van Loan, `Matrix Computations, 2nd edition'. `qzval (A, B)' Compute generalized eigenvalues. `syl (A, B, C)' Solve the Sylvester equation A X + X B + C = 0 using standard LAPACK subroutines.  File: octave.info, Node: Polynomial Manipulations, Next: Nonlinear Equations, Prev: Linear Algebra, Up: Top Polynomial Manipulations ************************ In Octave, a polynomial is represented by its coefficients (arranged in descending order). For example, a vector C of length N+1 corresponds to the following N-th order polynomial p(x) = c(1) x^n + ... + c(n) x + c(n+1). `compan (C)' Compute the companion matrix corresponding to polynomial coefficient vector C. The companion matrix is _ _ | -c(2)/c(1) -c(3)/c(1) ... -c(n)/c(1) -c(n+1)/c(1) | | 1 0 ... 0 0 | | 0 1 ... 0 0 | A = | . . . . . | | . . . . . | | . . . . . | |_ 0 0 ... 1 0 _| The eigenvalues of the companion matrix are equal to the roots of the polynomial. `conv (A, B)' Convolve two vectors. `y = conv (a, b)' returns a vector of length equal to `length (a) + length (b) - 1'. If A and B are polynomial coefficient vectors, `conv' returns the coefficients of the product polynomial. `deconv (Y, A)' Deconvolve two vectors. `[b, r] = deconv (y, a)' solves for B and R such that `y = conv (a, b) + r'. If Y and A are polynomial coefficient vectors, B will contain the coefficients of the polynomial quotient and R will be a remander polynomial of lowest order. `poly (A)' If A is a square N-by-N matrix, `poly (A)' is the row vector of the coefficients of `det (z * eye (n) - a)', the characteristic polynomial of A. If X is a vector, `poly (X)' is a vector of coefficients of the polynomial whose roots are the elements of X. `polyderiv (C)' Returns the coefficients of the derivative of the polynomial whose coefficients are given by vector C. `polyinteg (C)' Returns the coefficients of the integral the polynomial whose coefficients are represented by the vector C. The constant of integration is set to zero. `polyreduce (C)' Reduces a polynomial coefficient vector to a minimum number of terms by stripping off any leading zeros. `polyval (C, X)' Evaluate a polynomial. `polyval (C, X)' will evaluate the polynomial at the specified value of X. If X is a vector or matrix, the polynomial is evaluated at each of the elements of X. `polyvalm (C, X)' Evaluate a polynomial in the matrix sense. `polyvalm (C, X)' will evaluate the polynomial in the matrix sense, i.e. matrix multiplication is used instead of element by element multiplication as is used in polyval. The argument X must be a square matrix. `residue (B, A, TOL)' If B and A are vectors of polynomial coefficients, then residue calculates the partial fraction expansion corresponding to the ratio of the two polynomials. The function `residue' returns R, P, K, and E, where the vector R contains the residue terms, P contains the pole values, K contains the coefficients of a direct polynomial term (if it exists) and E is a vector containing the powers of the denominators in the partial fraction terms. Assuming B and A represent polynomials P (s) and Q(s) we have: P(s) M r(m) N ---- = SUM ------------- + SUM k(n)*s^(N-n) Q(s) m=1 (s-p(m))^e(m) n=1 where M is the number of poles (the length of the R, P, and E vectors) and N is the length of the K vector. The argument TOL is optional, and if not specified, a default value of 0.001 is assumed. The tolerance value is used to determine whether poles with small imaginary components are declared real. It is also used to determine if two poles are distinct. If the ratio of the imaginary part of a pole to the real part is less than TOL, the imaginary part is discarded. If two poles are farther apart than TOL they are distinct. For example, Example: b = [1, 1, 1]; a = [1, -5, 8, -4]; [r, p, k, e] = residue (b, a) returns r = [-2, 7, 3] p = [2, 2, 1] k = [](0x0) e = [1, 2, 1] which implies the following partial fraction expansion s^2 + s + 1 -2 7 3 ------------------- = ----- + ------- + ----- s^3 - 5s^2 + 8s - 4 (s-2) (s-2)^2 (s-1) `roots (V)' For a vector V with N components, return the roots of the polynomial v(1) * z^(n-1) + ... + v(n-1) * z + v(n).  File: octave.info, Node: Nonlinear Equations, Next: Differential Equations, Prev: Polynomial Manipulations, Up: Top Nonlinear Equations ******************* Octave can solve sets of nonlinear equations of the form F (x) = 0 using the function `fsolve', which is based on the MINPACK subroutine `hybrd'. For example, to solve the set of equations -2x^2 + 3xy + 4 sin(y) = 6 3x^2 - 2xy^2 + 3 cos(x) = -4 you first need to write a function to compute the value of the given function. For example: function y = f (x) y(1) = -2*x(1)^2 + 3*x(1)*x(2) + 4*sin(x(2)) - 6; y(2) = 3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4; endfunction Then, call `fsolve' with a specified initial condition to find the roots of the system of equations. For example, given the function `f' defined above, [x, info] = fsolve ("f", [1; 2]) results in the solution x = 0.57983 2.54621 info = 1 A value of `info = 1' indicates that the solution has converged. The function `perror' may be used to print English messages corresponding to the numeric error codes. For example, perror ("fsolve", 1) prints solution converged to requested tolerance Tolerances and other options for `fsolve' may be specified using the function `fsolve_options'.  File: octave.info, Node: Differential Equations, Next: Optimization, Prev: Nonlinear Equations, Up: Top Differential Equations ********************** Octave has two built-in functions for solving differential equations. Both are based on reliable ODE solvers written in Fortran. * Menu: * Ordinary Differential Equations:: * Differential-Algebraic Equations::