home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Geek Gadgets 1
/
ADE-1.bin
/
ade-dist
/
octave-1.1.1p1-bin.lha
/
info
/
octave.info-4
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1996-10-12
|
49KB
|
1,109 lines
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::