This is Info file octave.info, produced by Makeinfo-1.55 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 `"/usr/local/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 `/usr/local/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::

