home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / octave.info-4 < prev    next >
Encoding:
GNU Info File  |  1996-10-12  |  47.9 KB  |  1,527 lines
  1. This is Info file octave.info, produced by Makeinfo-1.64 from the input
  2. file octave.texi.
  3.  
  4.    Copyright (C) 1993, 1994, 1995 John W. Eaton.
  5.  
  6.    Permission is granted to make and distribute verbatim copies of this
  7. manual provided the copyright notice and this permission notice are
  8. preserved on all copies.
  9.  
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided that
  12. the entire resulting derived work is distributed under the terms of a
  13. permission notice identical to this one.
  14.  
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions.
  18.  
  19. 
  20. File: octave.info,  Node: User Preferences,  Next: Other Built-in Variables,  Prev: Predefined Constants,  Up: Built-in Variables
  21.  
  22. User Preferences
  23. ================
  24.  
  25.    This section describes the variables that you can use to customize
  26. Octave's behavior.
  27.  
  28.    Normally, preferences are set in the file `~/.octaverc', so that you
  29. can customize your environment in the same way each time you use Octave
  30. without having to remember and retype all the necessary commands.
  31. *Note Startup Files:: for more information.
  32.  
  33. `EDITOR'
  34.      A string naming the editor to use with the `edit_history' command.
  35.      If the environment variable `EDITOR' is set when Octave starts, its
  36.      value is used as the default.  Otherwise, `EDITOR' is set to
  37.      `"vi"'.
  38.  
  39. `IMAGEPATH'
  40.      A colon separated list of directories in which to search for image
  41.      files.  *Note Image Processing:: for a description of Octave's
  42.      image processing capabilities.
  43.  
  44. `INFO_FILE'
  45.      A string naming the location of the Octave info file.
  46.  
  47.      The default value is `"/ade/info/octave.info"'.
  48.  
  49. `LOADPATH'
  50.      A colon separated list of directories in which to search for
  51.      function files.  *Note Functions and Scripts::.  The value of
  52.      `LOADPATH' overrides the environment variable `OCTAVE_PATH'.
  53.      *Note Installation::.
  54.  
  55.      `LOADPATH' is now handled in the same way as TeX handles
  56.      `TEXINPUTS'.  If the path starts with `:', the standard path is
  57.      prepended to the value of `LOADPATH'.  If it ends with `:' the
  58.      standard path is appended to the value of `LOADPATH'.
  59.  
  60.      In addition, if any path element ends in `//', that directory and
  61.      all subdirectories it contains are searched recursively for
  62.      function files.  This can result in a slight delay as Octave
  63.      caches the lists of files found in the `LOADPATH' the first time
  64.      Octave searches for a function.  After that, searching is usually
  65.      much faster because Octave normally only needs to search its
  66.      internal cache for files.
  67.  
  68.      To improve performance of recursive directory searching, it is
  69.      best for each directory that is to be searched recursively to
  70.      contain *either* additional subdirectories *or* function files, but
  71.      not a mixture of both.
  72.  
  73.      *Note Organization of Functions:: for a description of the
  74.      function file directories that are distributed with Octave.
  75.  
  76. `OCTAVE_VERSION'
  77.      The version number of Octave, as a string.
  78.  
  79. `PAGER'
  80.      The default value is `"less"', or, if `less' is not available on
  81.      your system, `"more"'.  *Note Installation::, and *Note Input and
  82.      Output::.
  83.  
  84. `PS1'
  85.      The primary prompt string.  When executing interactively, Octave
  86.      displays the primary prompt `PS1' when it is ready to read a
  87.      command.  Octave allows the prompt to be customized by inserting a
  88.      number of backslash-escaped special characters that are decoded as
  89.      follows:
  90.  
  91.     `\t'
  92.           The time.
  93.  
  94.     `\d'
  95.           The date.
  96.  
  97.     `\n'
  98.           Begins a new line by printing the equivalent of a carriage
  99.           return followed by a line feed.
  100.  
  101.     `\s'
  102.           The name of the program (usually just `octave').
  103.  
  104.     `\w'
  105.           The current working directory.
  106.  
  107.     `\W'
  108.           The basename of the current working directory.
  109.  
  110.     `\u'
  111.           The username of the current user.
  112.  
  113.     `\h'
  114.           The hostname.
  115.  
  116.     `\#'
  117.           The command number of this command, counting from when Octave
  118.           starts.
  119.  
  120.     `\!'
  121.           The history number of this command.  This differs from `\#'
  122.           by the number of commands in the history list when Octave
  123.           starts.
  124.  
  125.     `\$'
  126.           If the effective UID is 0, a #, otherwise a $.
  127.  
  128.     `\nnn'
  129.           The character whose character code in octal is `nnn'.
  130.  
  131.     `\\'
  132.           A backslash.
  133.  
  134.      The default value of `PS1' is `"\s:\#> "'.  To change it, use a
  135.      command like
  136.  
  137.           octave:13> PS1 = "\\u@\\h> "
  138.  
  139.      which will result in the prompt `boris@kremvax> ' for the user
  140.      `boris' logged in on the host `kremvax'.  Note that two
  141.      backslashes are required to enter a backslash into a string.
  142.      *Note String Constants::.
  143.  
  144. `PS2'
  145.      The secondary prompt string, which is printed when Octave is
  146.      expecting additional input to complete a command.  For example,
  147.      when defining a function over several lines, Octave will print the
  148.      value of `PS1' at the beginning of each line after the first.
  149.      Octave allows `PS2' to be customized in the same way as `PS1'.
  150.      The default value of `PS2' is `"> "'.
  151.  
  152. `PS4'
  153.      If Octave is invoked with the `--echo-input' option, the value of
  154.      `PS4' is printed before each line of input that is echoed.  Octave
  155.      allows `PS4' to be customized in the same way as `PS1'.  The
  156.      default value of `PS4' is `"+ "'.  *Note Invoking Octave::, for a
  157.      description of `--echo-input'.
  158.  
  159. `automatic_replot'
  160.      If this variable is `"true"', Octave will automatically send a
  161.      `replot' command to `gnuplot' each time the plot changes.  Since
  162.      this is fairly inefficient, the default value is `"false"'.
  163.  
  164. `default_return_value'
  165.      The value given to otherwise unitialized return values if
  166.      `define_all_return_values' is `"true"'.  The default value is `[]'.
  167.  
  168. `default_save_format'
  169.      Specify the default format used by the `save' command.  Options are
  170.      `"ascii"', `"binary"', `"mat-binary"', or `"float-binary"'.  The
  171.      default value is `ascii'.
  172.  
  173. `define_all_return_values'
  174.      If the value of `define_all_return_values' is `"true"', Octave
  175.      will substitute the value specified by `default_return_value' for
  176.      any return values that remain undefined when a function returns.
  177.      The default value is `"false"'.
  178.  
  179. `do_fortran_indexing'
  180.      If the value of `do_fortran_indexing' is `"true"', Octave allows
  181.      you to select elements of a two-dimensional matrix using a single
  182.      index by treating the matrix as a single vector created from the
  183.      columns of the matrix.  The default value is `"false"'.
  184.  
  185. `empty_list_elements_ok'
  186.      This variable controls whether Octave ignores empty matrices in a
  187.      matrix list.
  188.  
  189.      For example, if the value of `empty_list_elements_ok' is `"true"',
  190.      Octave will ignore the empty matrices in the expression
  191.  
  192.           a = [1, [], 3, [], 5]
  193.  
  194.      and the variable `a' will be assigned the value `[ 1 3 5 ]'.
  195.  
  196.      The default value is `"warn"'.
  197.  
  198. `gnuplot_binary'
  199.      The name of the program invoked by the plot command.  The default
  200.      value is `"gnuplot"'.  *Note Installation::.
  201.  
  202. `ignore_function_time_stamp'
  203.      This variable variable can be used to prevent Octave from making
  204.      the system call `stat()' each time it looks up functions defined in
  205.      function files.  If `ignore_function_time_stamp' to `"system"',
  206.      Octave will not automatically recompile function files in
  207.      subdirectories of `/ade/lib/1.1.1' if they have changed since they
  208.      were last compiled, but will recompile other function files in the
  209.      `LOADPATH' if they change.  If set to `"all"', Octave will not
  210.      recompile any function files unless their definitions are removed
  211.      with `clear'.  For any other value of
  212.      `ignore_function_time_stamp', Octave will always check to see if
  213.      functions defined in function files need to recompiled.  The
  214.      default value of `ignore_function_time_stamp' is `"system"'.
  215.  
  216. `implicit_str_to_num_ok'
  217.      If the value of `implicit_str_to_num_ok' is `"true"', implicit
  218.      conversions of strings to their numeric ASCII equivalents are
  219.      allowed.  Otherwise, an error message is printed and control is
  220.      returned to the top level.  The default value is `"false"'.
  221.  
  222. `ok_to_lose_imaginary_part'
  223.      If the value of `ok_to_lose_imaginary_part' is `"true"', implicit
  224.      conversions of complex numbers to real numbers are allowed (for
  225.      example, by fsolve).  If the value is `"warn"', the conversion is
  226.      allowed, but a warning is printed.  Otherwise, an error message is
  227.      printed and control is returned to the top level.  The default
  228.      value is `"warn"'.
  229.  
  230. `output_max_field_width'
  231.      This variable specifies the maximum width of a numeric output
  232.      field.  The default value is 10.
  233.  
  234.      It is possible to achieve a wide range of output styles by using
  235.      different values of `output_precision' and
  236.      `output_max_field_width'.  Reasonable combinations can be set using
  237.      the `format' function.  *Note Basic Input and Output::.
  238.  
  239. `output_precision'
  240.      This variable specifies the minimum number of significant figures
  241.      to display for numeric output.  The default value is 5.
  242.  
  243.      It is possible to achieve a wide range of output styles by using
  244.      different values of `output_precision' and
  245.      `output_max_field_width'.  Reasonable combinations can be set using
  246.      the `format' function.  *Note Basic Input and Output::.
  247.  
  248. `page_screen_output'
  249.      If the value of `page_screen_output' is `"true"', all output
  250.      intended for the screen that is longer than one page is sent
  251.      through a pager.  This allows you to view one screenful at a time.
  252.      Some pagers (such as `less'--see *Note Installation::) are also
  253.      capable of moving backward on the output.  The default value is
  254.      `"true"'.  *Note Input and Output::.
  255.  
  256.      You can choose the program to use as the pager by setting the
  257.      variable `PAGER'.
  258.  
  259. `prefer_column_vectors'
  260.      If `prefer_column_vectors' is `"true"', operations like
  261.  
  262.           for i = 1:10
  263.             a (i) = i;
  264.           endfor
  265.  
  266.      (for `a' previously  undefined) produce column vectors.
  267.      Otherwise, row vectors are preferred.  The default value is
  268.      `"false"'.
  269.  
  270.      If a variable is already defined to be a vector (a matrix with a
  271.      single row or column), the original orientation is respected,
  272.      regardless of the value of `prefer_column_vectors'.
  273.  
  274. `prefer_zero_one_indexing'
  275.      If the value of `prefer_zero_one_indexing' is `"true"', Octave
  276.      will perform zero-one style indexing when there is a conflict with
  277.      the normal indexing rules.  *Note Index Expressions::.  For
  278.      example, given a matrix
  279.  
  280.           a = [1, 2, 3, 4]
  281.  
  282.      with `prefer_zero_one_indexing' is set to `"true"', the expression
  283.  
  284.           a ([1, 1, 1, 1])
  285.  
  286.      results in the matrix `[ 1  2  3  4 ]'.  If the value of
  287.      `prefer_zero_one_indexing' set to `"false"', the result would be
  288.      the matrix `[ 1 1 1 1 ]'.
  289.  
  290.      In the first case, Octave is selecting each element corresponding
  291.      to a `1' in the index vector.  In the second, Octave is selecting
  292.      the first element multiple times.
  293.  
  294.      The default value for `prefer_zero_one_indexing' is `"false"'.
  295.  
  296. `print_answer_id_name'
  297.      If the value of `print_answer_id_name' is `"true"', variable names
  298.      are printed along with the result.  Otherwise, only the result
  299.      values are printed.  The default value is `"true"'.
  300.  
  301. `print_empty_dimensions'
  302.      If the value of `print_empty_dimensions' is `"true"', the
  303.      dimensions of empty matrices are printed along with the empty
  304.      matrix symbol, `[]'.  For example, the expression
  305.  
  306.           zeros (3, 0)
  307.  
  308.      will print
  309.  
  310.           ans =
  311.           
  312.           [](3x0)
  313.  
  314. `propagate_empty_matrices'
  315.      If the value of `propagate_empty_matrices' is `"true"', functions
  316.      like `inverse' and `svd' will return an empty matrix if they are
  317.      given one as an argument.  The default value is `"true"'.  *Note
  318.      Empty Matrices::.
  319.  
  320. `resize_on_range_error'
  321.      If the value of `resize_on_range_error' is `"true"', expressions
  322.      like
  323.  
  324.           for i = 1:10
  325.             a (i) = i;
  326.           endfor
  327.  
  328.      (for `a' previously undefined) result in the variable `a' being
  329.      resized to be just large enough to hold the new value.  Otherwise
  330.      uninitialized elements are set to zero.  If the value of
  331.      `resize_on_range_error' is `"false"', an error message is printed
  332.      and control is returned to the top level.  The default value is
  333.      `"true"'.
  334.  
  335. `return_last_computed_value'
  336.      If the value of `return_last_computed_value' is true, and a
  337.      function is defined without explicitly specifying a return value,
  338.      the function will return the value of the last expression.
  339.      Otherwise, no value will be returned.  The default value is
  340.      `"false"'.
  341.  
  342.      For example, the function
  343.  
  344.           function f ()
  345.             2 + 2;
  346.           endfunction
  347.  
  348.      will either return nothing, if `return_last_computed_value' is
  349.      `"false"', or 4, if it is `"true"'.
  350.  
  351. `save_precision'
  352.      This variable specifies the number of digits to keep when saving
  353.      data with the `save' command.  The default value is 17.
  354.  
  355. `silent_functions'
  356.      If the value of `silent_functions' is `"true"', internal output
  357.      from a function is suppressed.  Otherwise, the results of
  358.      expressions within a function body that are not terminated with a
  359.      semicolon will have their values printed.  The default value is
  360.      `"false"'.
  361.  
  362.      For example, if the function
  363.  
  364.           function f ()
  365.             2 + 2
  366.           endfunction
  367.  
  368.      is executed, Octave will either print `ans = 4' or nothing
  369.      depending on the value of `silent_functions'.
  370.  
  371. `split_long_rows'
  372.      For large matrices, Octave may not be able to display all the
  373.      columns of a given row on one line of your screen.  This can
  374.      result in missing information or output that is nearly impossible
  375.      to decipher, depending on whether your terminal truncates or wraps
  376.      long lines.
  377.  
  378.      If the value of `split_long_rows' is `"true"', Octave will display
  379.      the matrix in a series of smaller pieces, each of which can fit
  380.      within the limits of your terminal width.  Each set of rows is
  381.      labeled so that you can easily see which columns are currently
  382.      being displayed.  For example:
  383.  
  384.           octave:13> rand (2, 9)
  385.           ans =
  386.           
  387.            Columns 1 through 7:
  388.           
  389.              0.92205  0.72628  0.99841  0.62590  0.82422  0.77486  0.30258
  390.              0.15999  0.79484  0.75443  0.86995  0.91430  0.23980  0.64591
  391.           
  392.            Columns 8 and 9:
  393.           
  394.             0.08894  0.13266
  395.             0.28008  0.65575
  396.  
  397.      The default value of `split_long_rows' is `"true"'.
  398.  
  399. `suppress_verbose_help_message'
  400.      If the value of `suppress_verbose_help_message' is `"true"',
  401.      Octave will not add additional help information to the end of the
  402.      output from the `help' command and usage messages for built-in
  403.      commands.
  404.  
  405. `treat_neg_dim_as_zero'
  406.      If the value of `treat_neg_dim_as_zero' is `"true"', expressions
  407.      like
  408.  
  409.           eye (-1)
  410.  
  411.      produce an empty matrix (i.e., row and column dimensions are zero).
  412.      Otherwise, an error message is printed and control is returned to
  413.      the top level.  The default value is `"false"'.
  414.  
  415. `warn_assign_as_truth_value'
  416.      If the value of `warn_assign_as_truth_value' is `"true"', a
  417.      warning is issued for statements like
  418.  
  419.           if (s = t)
  420.             ...
  421.  
  422.      since such statements are not common, and it is likely that the
  423.      intent was to write
  424.  
  425.           if (s == t)
  426.             ...
  427.  
  428.      instead.
  429.  
  430.      There are times when it is useful to write code that contains
  431.      assignments within the condition of a `while' or `if' statement.
  432.      For example, statements like
  433.  
  434.           while (c = getc())
  435.             ...
  436.  
  437.      are common in C programming.
  438.  
  439.      It is possible to avoid all warnings about such statements by
  440.      setting `warn_assign_as_truth_value' to `"false"', but that may
  441.      also let real errors like
  442.  
  443.           if (x = 1)  # intended to test (x == 1)!
  444.             ...
  445.  
  446.      slip by.
  447.  
  448.      In such cases, it is possible suppress errors for specific
  449.      statements by writing them with an extra set of parentheses.  For
  450.      example, writing the previous example as
  451.  
  452.           while ((c = getc()))
  453.             ...
  454.  
  455.      will prevent the warning from being printed for this statement,
  456.      while allowing Octave to warn about other assignments used in
  457.      conditional contexts.
  458.  
  459.      The default value of `warn_assign_as_truth_value' is `"true"'.
  460.  
  461. `warn_comma_in_global_decl'
  462.      If the value of `warn_comma_in_global_decl' is `"true"', a warning
  463.      is issued for statements like
  464.  
  465.           global a = 1, b
  466.  
  467.      which makes the variables `a' and `b' global and assigns the value
  468.      1 to the variable `a', because in this context, the comma is not
  469.      interpreted as a statement separator.
  470.  
  471.      The default value of `warn_comma_in_global_decl' is `"true"'.
  472.  
  473. `warn_divide_by_zero'
  474.      If the value of `warn_divide_by_zero' is `"true"', a warning is
  475.      issued when Octave encounters a division by zero.  If the value is
  476.      `"false"', the warning is omitted.  The default value is `"true"'.
  477.  
  478. `warn_function_name_clash'
  479.      If the value of `warn_function_name_clash' is `"true"', a warning
  480.      is issued when Octave finds that the name of a function defined in
  481.      a function file differs from the name of the file.  If the value is
  482.      `"false"', the warning is omitted.  The default value is `"true"'.
  483.  
  484. `whitespace_in_literal_matrix'
  485.      This variable allows some control over how Octave decides to
  486.      convert spaces to commas and semicolons in matrix expressions like
  487.      `[m (1)]' or
  488.  
  489.           [ 1, 2,
  490.             3, 4 ]
  491.  
  492.      If the value of `whitespace_in_literal_matrix' is `"ignore"',
  493.      Octave will never insert a comma or a semicolon in a literal matrix
  494.      list.  For example, the expression `[1 2]' will result in an error
  495.      instead of being treated the same as `[1, 2]', and the expression
  496.  
  497.           [ 1, 2,
  498.             3, 4 ]
  499.  
  500.      will result in the vector [1 2 3 4] instead of a matrix.
  501.  
  502.      If the value of `whitespace_in_literal_matrix' is `"traditional"',
  503.      Octave will convert spaces to a comma between identifiers and `('.
  504.      For example, given the matrix
  505.  
  506.           m = [3 2]
  507.  
  508.      the expression
  509.  
  510.           [m (1)]
  511.  
  512.      will be parsed as
  513.  
  514.           [m, (1)]
  515.  
  516.      and will result in
  517.  
  518.           [3 2 1]
  519.  
  520.      and the expression
  521.  
  522.           [ 1, 2,
  523.             3, 4 ]
  524.  
  525.      will result in a matrix because the newline character is converted
  526.      to a semicolon (row separator) even though there is a comma at the
  527.      end of the first line (trailing commas or semicolons are ignored).
  528.      This is apparently how MATLAB behaves.
  529.  
  530.      Any other value for `whitespace_in_literal_matrix' results in
  531.      behavior that is the same as traditional, except that Octave does
  532.      not convert spaces to a comma between identifiers and `('.  For
  533.      example, the expression
  534.  
  535.           [m (1)]
  536.  
  537.      will produce `3'.  This is the way Octave has always behaved.
  538.  
  539. 
  540. File: octave.info,  Node: Other Built-in Variables,  Next: Summary of Preference Variables,  Prev: User Preferences,  Up: Built-in Variables
  541.  
  542. Other Built-in Variables
  543. ========================
  544.  
  545.    In addition to these variables, there are two other special built-in
  546. variables whose values are automatically updated.
  547.  
  548. `ans'
  549.      This variable holds the most recently computed result that was not
  550.      explicitly assigned to a variable.  For example, after the
  551.      expression
  552.  
  553.           3^2 + 4^2
  554.  
  555.      is evaluated, the value of `ans' is `25'.
  556.  
  557. `PWD'
  558.      The current working directory.  The value of `PWD' is updated each
  559.      time the current working directory is changed with the `cd'
  560.      command.  *Note System Utilities::.
  561.  
  562. 
  563. File: octave.info,  Node: Summary of Preference Variables,  Prev: Other Built-in Variables,  Up: Built-in Variables
  564.  
  565. Summary of Preference Variables
  566. ===============================
  567.  
  568.    Here is a summary of all of Octave's preference variables and their
  569. default values.  In the following table `OCTAVE_HOME' stands for the
  570. root directory where Octave is installed, and `VERSION' stands for the
  571. Octave version number.
  572.  
  573.      EDITOR                        EDITOR environment variable, or "vi"
  574.      INFO_FILE                     "OCTAVE_HOME/info/octave.info"
  575.      LOADPATH                      OCTAVE_PATH environment variable, or
  576.                                    ".:OCTAVE_HOME/lib/VERSION"
  577.      PAGER                         "less", or "more"
  578.      PS1                           "\s:\#> "
  579.      PS2                           "> "
  580.      PS4                           "+ "
  581.      automatic_replot              "false"
  582.      default_return_value          []
  583.      do_fortran_indexing           "false"
  584.      define_all_return_values      "false"
  585.      empty_list_elements_ok        "warn"
  586.      gnuplot_binary                "gnuplot"
  587.      ignore_function_time_stamp    "system"
  588.      implicit_str_to_num_ok        "false"
  589.      ok_to_lose_imaginary_part     "warn"
  590.      output_max_field_width        10
  591.      output_precision              5
  592.      page_screen_output            "true"
  593.      prefer_column_vectors         "false"
  594.      prefer_zero_one_indexing      "false"
  595.      print_answer_id_name          "true"
  596.      print_empty_dimensions        "true"
  597.      resize_on_range_error         "true"
  598.      return_last_computed_value    "false"
  599.      save_precision                17
  600.      silent_functions              "false"
  601.      split_long_rows               "true"
  602.      suppress_verbose_help_message "true"
  603.      treat_neg_dim_as_zero         "false"
  604.      warn_assign_as_truth_value    "true"
  605.      warn_comma_in_global_decl     "true"
  606.      warn_divide_by_zero           "true"
  607.      warn_function_name_clash      "true"
  608.      whitespace_in_literal_matrix  ""
  609.  
  610. 
  611. File: octave.info,  Node: Arithmetic,  Next: Linear Algebra,  Prev: Built-in Variables,  Up: Top
  612.  
  613. Arithmetic
  614. **********
  615.  
  616.    Unless otherwise noted, all of the functions described in this
  617. chapter will work for real and complex scalar or matrix arguments.
  618.  
  619. * Menu:
  620.  
  621. * Utility Functions::
  622. * Complex Arithmetic::
  623. * Trigonometry::
  624. * Sums and Products::
  625. * Special Functions::
  626.  
  627. 
  628. File: octave.info,  Node: Utility Functions,  Next: Complex Arithmetic,  Prev: Arithmetic,  Up: Arithmetic
  629.  
  630. Utility Functions
  631. =================
  632.  
  633.    The following functions are available for working with complex
  634. numbers.  Each expects a single argument, and given a matrix, they work
  635. on an element by element basis.
  636.  
  637. `ceil (X)'
  638.      Return the smallest integer not less than X.  If X is complex,
  639.      return `ceil (real (X)) + ceil (imag (X)) * I'.
  640.  
  641. `floor (X)'
  642.      Return the largest integer not greater than X.  If X is complex,
  643.      return `floor (real (X)) + floor (imag (X)) * I'.
  644.  
  645. `fix (X)'
  646.      Truncate X toward zero.  If X is complex, return `fix (real (X)) +
  647.      fix (imag (X)) * I'.
  648.  
  649. `round (X)'
  650.      Return the integer nearest to X.  If X is complex, return `round
  651.      (real (X)) + round (imag (X)) * I'.
  652.  
  653. `sign (X)'
  654.      Compute the "signum" function, which is defined as
  655.  
  656.                      -1, x < 0;
  657.           sign (x) =  0, x = 0;
  658.                       1, x > 0.
  659.  
  660.      For complex arguments, `sign' returns `x ./ abs (X)'.
  661.  
  662. `exp (X)'
  663.      Compute the exponential of X.  To compute the matrix exponential,
  664.      see *Note Linear Algebra::.
  665.  
  666. `gcd (X, `...')'
  667.      Compute the greatest common divisor of the elements of X, or the
  668.      list of all the arguments.  For example,
  669.  
  670.           gcd (a1, ..., ak)
  671.  
  672.      is the same as
  673.  
  674.           gcd ([a1, ..., ak])
  675.  
  676.      An optional second return value, V contains an integer vector such
  677.      that
  678.  
  679.           g = v(1) * a(k) + ... + v(k) * a(k)
  680.  
  681. `lcm (X, `...')'
  682.      Compute the least common multiple of the elements elements of X, or
  683.      the list of all the arguments.  For example,
  684.  
  685.           lcm (a1, ..., ak)
  686.  
  687.      is the same as
  688.  
  689.           lcm ([a1, ..., ak]).
  690.  
  691. `log (X)'
  692.      Compute the natural logarithm of X.  To compute the matrix
  693.      logarithm, see *Note Linear Algebra::.
  694.  
  695. `log2 (X)'
  696.      Compute the base-2 logarithm of X.
  697.  
  698. `log10 (X)'
  699.      Compute the base-10 logarithm of X.
  700.  
  701. `sqrt (X)'
  702.      Compute the square root of X.  To compute the matrix square root,
  703.      see *Note Linear Algebra::.
  704.  
  705. `max (X)'
  706.      For a vector argument, return the maximum value.  For a matrix
  707.      argument, return the maximum value from each column, as a row
  708.      vector.  Thus,
  709.  
  710.           max (max (X))
  711.  
  712.      returns the largest element of X.
  713.  
  714.      For complex arguments, the magnitude of the elements are used for
  715.      comparison.
  716.  
  717. `min (X)'
  718.      Like `max', but return the minimum value.
  719.  
  720. `rem (X, Y)'
  721.      Return the remainder of `X / Y', computed using the expression
  722.  
  723.           x - y .* fix (x ./ y)
  724.  
  725.      An error message is printed if the dimensions of the arguments do
  726.      not agree, or if either of the arguments is complex.
  727.  
  728. 
  729. File: octave.info,  Node: Complex Arithmetic,  Next: Trigonometry,  Prev: Utility Functions,  Up: Arithmetic
  730.  
  731. Complex Arithmetic
  732. ==================
  733.  
  734.    The following functions are available for working with complex
  735. numbers.  Each expects a single argument.  Given a matrix they work on
  736. an element by element basis.
  737.  
  738. `abs (X)'
  739.      Compute the magnitude of X.
  740.  
  741. `angle (X)'
  742. `arg (X)'
  743.      Compute the argument of X.
  744.  
  745. `conj (X)'
  746.      Return the complex conjugate of X.
  747.  
  748. `imag (X)'
  749.      Return the imaginary part of X.
  750.  
  751. `real (X)'
  752.      Return the real part of X.
  753.  
  754. 
  755. File: octave.info,  Node: Trigonometry,  Next: Sums and Products,  Prev: Complex Arithmetic,  Up: Arithmetic
  756.  
  757. Trigonometry
  758. ============
  759.  
  760.    Octave provides the following trigonometric functions:
  761.  
  762.      sin    asin    sinh    asinh
  763.      cos    acos    cosh    acosh
  764.      tan    atan    tanh    atanh
  765.      
  766.      sec    asec    sech    asech
  767.      csc    acsc    csch    acsch
  768.      cot    acot    coth    acoth
  769.  
  770. Each of these functions expect a single argument.  For matrix arguments,
  771. they work on an element by element basis.  For example, the expression
  772.  
  773.      sin ([1, 2; 3, 4])
  774.  
  775. produces
  776.  
  777.      ans =
  778.      
  779.         0.84147   0.90930
  780.         0.14112  -0.75680
  781.  
  782.    `atan2 (Y, X)'
  783.  
  784. 
  785. File: octave.info,  Node: Sums and Products,  Next: Special Functions,  Prev: Trigonometry,  Up: Arithmetic
  786.  
  787. Sums and Products
  788. =================
  789.  
  790. `sum (X)'
  791.      For a vector argument, return the sum of all the elements.  For a
  792.      matrix argument, return the sum of the elements in each column, as
  793.      a row vector.  The sum of an empty matrix is 0 if it has no
  794.      columns, or a vector of zeros if it has no rows (*note Empty
  795.      Matrices::.).
  796.  
  797. `prod (X)'
  798.      For a vector argument, return the product of all the elements.
  799.      For a matrix argument, return the product of the elements in each
  800.      column, as a row vector.  The product of an empty matrix is 1 if
  801.      it has no columns, or a vector of ones if it has no rows (*note
  802.      Empty Matrices::.).
  803.  
  804. `cumsum (X)'
  805.      Return the cumulative sum of each column of X.  For example,
  806.  
  807.           cumsum ([1, 2; 3, 4])
  808.  
  809.      produces
  810.  
  811.           ans =
  812.           
  813.             1  2
  814.             4  6
  815.  
  816. `cumprod (X)'
  817.      Return the cumulative product of each column of X.  For example,
  818.  
  819.           cumprod ([1, 2; 3, 4])
  820.  
  821.      produces
  822.  
  823.           ans =
  824.           
  825.             1  2
  826.             3  8
  827.  
  828. `sumsq (X)'
  829.      For a vector argument, return the sum of the squares of all the
  830.      elements.  For a matrix argument, return the sum of the squares of
  831.      the elements in each column, as a row vector.
  832.  
  833. 
  834. File: octave.info,  Node: Special Functions,  Prev: Sums and Products,  Up: Arithmetic
  835.  
  836. Special Functions
  837. =================
  838.  
  839. `beta'
  840.      Returns the beta function,
  841.  
  842.           beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).
  843.  
  844. `betai (A, B, X)'
  845.      Returns the incomplete beta function,
  846.  
  847.                                               x
  848.                                              /
  849.           betai (a, b, x) = beta (a, b)^(-1) | t^(a-1) (1-t)^(b-1) dt.
  850.                                              /
  851.                                           t=0
  852.  
  853.      If x has more than one component, both A and B must be scalars.
  854.      If X is a scalar, A and B must be of compatible dimensions.
  855.  
  856. `erf'
  857.      Computes the error function,
  858.  
  859.                                    z
  860.                                   /
  861.           erf (z) = (2/sqrt (pi)) | e^(-t^2) dt
  862.                                   /
  863.                                t=0
  864.  
  865. `erfc (Z)'
  866.      Computes the complementary error function, `1 - erf (Z)'.
  867.  
  868. `erfinv'
  869.      Computes the inverse of the error function.
  870.  
  871. `gamma (Z)'
  872.      Computes the gamma function,
  873.  
  874.                       infinity
  875.                       /
  876.           gamma (z) = | t^(z-1) exp (-t) dt.
  877.                       /
  878.                    t=0
  879.  
  880. `gammai (A, X)'
  881.      Computes the incomplete gamma function,
  882.  
  883.                                         x
  884.                               1        /
  885.           gammai (a, x) = ---------    | exp (-t) t^(a-1) dt
  886.                           gamma (a)    /
  887.                                     t=0
  888.  
  889.      If A is scalar, then `gammai (A, X)' is returned for each element
  890.      of X and vice versa.
  891.  
  892.      If neither A nor X is scalar, the sizes of A and X must agree, and
  893.      GAMMAI is applied element-by-element.
  894.  
  895. `lgamma'
  896.      Returns the natural logarithm of the gamma function.
  897.  
  898. 
  899. File: octave.info,  Node: Linear Algebra,  Next: Polynomial Manipulations,  Prev: Arithmetic,  Up: Top
  900.  
  901. Linear Algebra
  902. **************
  903.  
  904.    This chapter documents the linear algebra functions of Octave.
  905. Reference material for many of these options may be found in Golub and
  906. Van Loan, `Matrix Computations, 2nd Ed.', Johns Hopkins, 1989, and in
  907. `LAPACK Users' Guide', SIAM, 1992.
  908.  
  909. * Menu:
  910.  
  911. * Basic Matrix Functions::
  912. * Matrix Factorizations::
  913. * Functions of a Matrix::
  914.  
  915. 
  916. File: octave.info,  Node: Basic Matrix Functions,  Next: Matrix Factorizations,  Prev: Linear Algebra,  Up: Linear Algebra
  917.  
  918. Basic Matrix Functions
  919. ======================
  920.  
  921. `balance'
  922.           aa = balance (a, opt)
  923.           [dd, aa] =  balance(a, opt)
  924.           [dd, aa] = balance (a, opt)
  925.           [cc, dd, aa, bb] = balance (a, b, opt)
  926.  
  927.      `[dd, aa] = balance (a)' returns `aa = dd \ a * dd'.  `aa' is a
  928.      matrix whose row/column norms are roughly equal in magnitude, and
  929.      `dd' = `p * d', where `p' is a permutation matrix and `d' is a
  930.      diagonal matrix of powers of two.  This allows the equilibration
  931.      to be computed without roundoff.  Results of eigenvalue
  932.      calculation are typically improved by balancing first.
  933.  
  934.      `[cc, dd, aa, bb] = balance (a, b)'  returns `aa' (`bb') `=
  935.      cc*a*dd (cc*b*dd)'), where `aa' and `bb' have non-zero elements of
  936.      approximately the same magnitude and `cc' and `dd'  are permuted
  937.      diagonal matrices as in `dd' for the algebraic eigenvalue problem.
  938.  
  939.      The eigenvalue balancing option `opt' is selected as follows:
  940.  
  941.     `"N"', `"n"'
  942.           No balancing; arguments copied, transformation(s) set to
  943.           identity.
  944.  
  945.     `"P"', `"p"'
  946.           Permute argument(s) to isolate eigenvalues where possible.
  947.  
  948.     `"S"', `"s"'
  949.           Scale to improve accuracy of computed eigenvalues.
  950.  
  951.     `"B"', `"b"'
  952.           Permute and scale, in that order. Rows/columns of a (and b)
  953.           that are isolated by permutation are not scaled.  This is the
  954.           default behavior.
  955.  
  956.      Algebraic eigenvalue balancing uses standard LAPACK routines.
  957.  
  958.      Generalized eigenvalue problem balancing uses Ward's algorithm
  959.      (SIAM Journal on Scientific and Statistical Computing, 1981).
  960.  
  961. `cond (A)'
  962.      Compute the (two-norm) condition number of a matrix. `cond (a)' is
  963.      defined as `norm (a) * norm (inv (a))', and is computed via a
  964.      singular value decomposition.
  965.  
  966. `det (A)'
  967.      Compute the determinant of A using LINPACK.
  968.  
  969. `eig'
  970.                       = eig (a)
  971.           [v, lambda] = eig (a)
  972.  
  973.      The eigenvalues (and eigenvectors) of a matrix are computed in a
  974.      several step process which begins with a Hessenberg decomposition
  975.      (see `hess'), followed by a Schur decomposition (see `schur'), from
  976.      which the eigenvalues are apparent.  The eigenvectors, when
  977.      desired, are computed by further manipulations of the Schur
  978.      decomposition.
  979.  
  980.      See also: `hess', `schur'.
  981.  
  982. `givens'
  983.           [c, s] = givens (x, y)
  984.           G = givens (x, y)
  985.  
  986.      `G = givens(x, y)' returns a 2 x 2 orthogonal matrix `G = [c s;
  987.      -s' c]' such that `G [x; y] = [*; 0]'  (x, y scalars)
  988.  
  989. `inv (A)'
  990. `inverse (A)'
  991.      Compute the inverse of the square matrix A.
  992.  
  993. `norm (A, P)'
  994.      Compute the p-norm of the matrix A.  If the second argument is
  995.      missing, `p = 2' is assumed.
  996.  
  997.      If A is a matrix:
  998.  
  999.     P = `1'
  1000.           1-norm, the largest column sum of A.
  1001.  
  1002.     P = `2'
  1003.           Largest singular value of A.
  1004.  
  1005.     P = `Inf'
  1006.           Infinity norm, the largest row sum of A.
  1007.  
  1008.     P = `"fro"'
  1009.           Frobenius norm of A, `sqrt (sum (diag (a' * a)))'.
  1010.  
  1011.      If A is a vector or a scalar:
  1012.  
  1013.     P = `Inf'
  1014.           `max (abs (a))'.
  1015.  
  1016.     P = `-Inf'
  1017.           `min (abs (a))'.
  1018.  
  1019.     other
  1020.           p-norm of A, `(sum (abs (a) .^ p)) ^ (1/p)'.
  1021.  
  1022. `null (A, TOL)'
  1023.      Returns an orthonormal basis of the null space of A.
  1024.  
  1025.      The dimension of the null space is taken as the number of singular
  1026.      values of A not greater than TOL.  If the argument TOL is missing,
  1027.      it is computed as
  1028.  
  1029.           max (size (a)) * max (svd (a)) * eps
  1030.  
  1031. `orth (A, TOL)'
  1032.      Returns an orthonormal basis of the range of A.
  1033.  
  1034.      The dimension of the range space is taken as the number of singular
  1035.      values of A greater than TOL.  If the argument TOL is missing, it
  1036.      is computed as
  1037.  
  1038.           max (size (a)) * max (svd (a)) * eps
  1039.  
  1040. `pinv (X, TOL)'
  1041.      Returns the pseudoinverse of X.  Singular values less than TOL are
  1042.      ignored.
  1043.  
  1044.      If the second argument is omitted, it is assumed that
  1045.  
  1046.           tol = max (size (X)) * sigma_max (X) * eps,
  1047.  
  1048.      where `sigma_max (X)' is the maximal singular value of X.
  1049.  
  1050. `rank (A, TOL)'
  1051.      Compute the rank of A, using the singular value decomposition.
  1052.      The rank is taken to be the number  of singular values of A that
  1053.      are greater than the specified tolerance TOL.  If the second
  1054.      argument is omitted, it is taken to be
  1055.  
  1056.           tol =  max (size (a)) * sigma (1) * eps;
  1057.  
  1058.      where `eps' is machine precision and `sigma' is the largest
  1059.      singular value of `a'.
  1060.  
  1061. `trace (A)'
  1062.      Compute the trace of A, `sum (diag (a))'.
  1063.  
  1064. 
  1065. File: octave.info,  Node: Matrix Factorizations,  Next: Functions of a Matrix,  Prev: Basic Matrix Functions,  Up: Linear Algebra
  1066.  
  1067. Matrix Factorizations
  1068. =====================
  1069.  
  1070. `chol (A)'
  1071.      Compute the Cholesky factor, R, of the symmetric positive definite
  1072.      matrix A, where
  1073.  
  1074.           r' * r = a.
  1075.  
  1076. `hess (A)'
  1077.      Compute the Hessenberg decomposition of the matrix A.
  1078.  
  1079.                h = hess (a)
  1080.           [p, h] = hess (a)
  1081.  
  1082.      The Hessenberg decomposition is usually used as the first step in
  1083.      an eigenvalue computation, but has other applications as well (see
  1084.      Golub, Nash, and Van Loan, IEEE Transactions on Automatic Control,
  1085.      1979.  The Hessenberg decomposition is `p * h * p' = a' where `p'
  1086.      is a square unitary matrix (`p' * p = I', using complex-conjugate
  1087.      transposition) and `h' is upper Hessenberg (`i >= j+1 => h (i, j)
  1088.      = 0').
  1089.  
  1090. `lu (A)'
  1091.      Compute the LU decomposition of A, using subroutines from LAPACK.
  1092.      The result is returned in a permuted form, according to the
  1093.      optional return value P.  For example, given the matrix `a = [1,
  1094.      2; 3, 4]',
  1095.  
  1096.           [l, u, p] = lu (a)
  1097.  
  1098.      returns
  1099.  
  1100.           l =
  1101.           
  1102.             1.00000  0.00000
  1103.             0.33333  1.00000
  1104.           
  1105.           u =
  1106.           
  1107.             3.00000  4.00000
  1108.             0.00000  0.66667
  1109.           
  1110.           p =
  1111.           
  1112.             0  1
  1113.             1  0
  1114.  
  1115. `qr (A)'
  1116.      Compute the QR factorization of A, using standard LAPACK
  1117.      subroutines.  For example, given the matrix `a = [1, 2; 3, 4]',
  1118.  
  1119.           [q, r] = qr (a)
  1120.  
  1121.      returns
  1122.  
  1123.           q =
  1124.           
  1125.             -0.31623  -0.94868
  1126.             -0.94868   0.31623
  1127.           
  1128.           r =
  1129.           
  1130.             -3.16228  -4.42719
  1131.              0.00000  -0.63246
  1132.  
  1133.      The `qr' factorization has applications in the solution of least
  1134.      squares problems
  1135.  
  1136.           `min norm(A x - b)'
  1137.  
  1138.      for overdetermined systems of equations (i.e., `a'  is a tall,
  1139.      thin matrix).  The `qr' factorization is `q * r = a' where `q' is
  1140.      an orthogonal matrix and `r' is upper triangular.
  1141.  
  1142.      The permuted `qr' factorization `[q, r, pi] = qr (a)' forms the
  1143.      `qr' factorization such that the diagonal entries of `r' are
  1144.      decreasing in magnitude order.  For example, given the matrix `a =
  1145.      [1, 2; 3, 4]',
  1146.  
  1147.           [q, r, pi] = qr(a)
  1148.  
  1149.      returns
  1150.  
  1151.           q =
  1152.           
  1153.             -0.44721  -0.89443
  1154.             -0.89443   0.44721
  1155.           
  1156.           r =
  1157.           
  1158.             -4.47214  -3.13050
  1159.              0.00000   0.44721
  1160.           
  1161.           p =
  1162.           
  1163.              0  1
  1164.              1  0
  1165.  
  1166.      The permuted `qr' factorization `[q, r, pi] = qr (a)'
  1167.      factorization allows the construction of an orthogonal basis of
  1168.      `span (a)'.
  1169.  
  1170. `schur'
  1171.           [u, s] = schur (a, opt)   opt = "a", "d", or "u"
  1172.                s = schur (a)
  1173.  
  1174.      The Schur decomposition is used to compute eigenvalues of a square
  1175.      matrix, and has applications in the solution of algebraic Riccati
  1176.      equations in control (see `are' and `dare').  `schur' always
  1177.      returns `s = u' * a * u' where `u'  is a unitary matrix (`u'* u'
  1178.      is identity) and `s' is upper triangular.  The eigenvalues of `a'
  1179.      (and `s') are the diagonal elements of `s' If the matrix `a' is
  1180.      real, then the real Schur decomposition is computed, in which the
  1181.      matrix `u' is orthogonal and `s' is block upper triangular with
  1182.      blocks of size at most `2 x 2' blocks along the diagonal.  The
  1183.      diagonal elements of `s' (or the eigenvalues of the `2 x 2'
  1184.      blocks, when appropriate) are the eigenvalues of `a' and `s'.
  1185.  
  1186.      The eigenvalues are optionally ordered along the diagonal
  1187.      according to the value of `opt'.  `opt = "a"' indicates that all
  1188.      eigenvalues with negative real parts should be moved to the leading
  1189.      block of `s' (used in `are'), `opt = "d"' indicates that all
  1190.      eigenvalues with magnitude less than one should be moved to the
  1191.      leading block of `s' (used in `dare'), and `opt = "u"', the
  1192.      default, indicates that no ordering of eigenvalues should occur.
  1193.      The leading `k' columns of `u' always span the `a'-invariant
  1194.      subspace corresponding to the `k' leading eigenvalues of `s'.
  1195.  
  1196. `svd (A)'
  1197.      Compute the singular value decomposition of A
  1198.  
  1199.           a = u * sigma * v'
  1200.  
  1201.      The function `svd' normally returns the vector of singular values.
  1202.      If asked for three return values, it computes U, S, and V.  For
  1203.      example,
  1204.  
  1205.           svd (hilb (3))
  1206.  
  1207.      returns
  1208.  
  1209.           ans =
  1210.           
  1211.             1.4083189
  1212.             0.1223271
  1213.             0.0026873
  1214.  
  1215.      and
  1216.  
  1217.           [u, s, v] = svd (hilb (3))
  1218.  
  1219.      returns
  1220.  
  1221.           u =
  1222.           
  1223.             -0.82704   0.54745   0.12766
  1224.             -0.45986  -0.52829  -0.71375
  1225.             -0.32330  -0.64901   0.68867
  1226.           
  1227.           s =
  1228.           
  1229.             1.40832  0.00000  0.00000
  1230.             0.00000  0.12233  0.00000
  1231.             0.00000  0.00000  0.00269
  1232.           
  1233.           v =
  1234.           
  1235.             -0.82704   0.54745   0.12766
  1236.             -0.45986  -0.52829  -0.71375
  1237.             -0.32330  -0.64901   0.68867
  1238.  
  1239.      If given a second argument, `svd' returns an economy-sized
  1240.      decomposition, eliminating the unnecessary rows or columns of U or
  1241.      V.
  1242.  
  1243. 
  1244. File: octave.info,  Node: Functions of a Matrix,  Prev: Matrix Factorizations,  Up: Linear Algebra
  1245.  
  1246. Functions of a Matrix
  1247. =====================
  1248.  
  1249. `expm'
  1250.           expm (a)
  1251.  
  1252.      Returns the exponential of a matrix, defined as the infinite
  1253.      Taylor series
  1254.  
  1255.           expm(a) = I + a + a^2/2! + a^3/3! + ...
  1256.  
  1257.      The Taylor series is *not* the way to compute the matrix
  1258.      exponential; see Moler and Van Loan, `Nineteen Dubious Ways to
  1259.      Compute the Exponential of a Matrix', SIAM Review, 1978.  This
  1260.      routine uses Ward's diagonal Pade' approximation method with three
  1261.      step preconditioning (SIAM Journal on Numerical Analysis, 1977).
  1262.  
  1263.      Diagonal Pade'  approximations are rational polynomials of matrices
  1264.  
  1265.                -1
  1266.           D (a)   N (a)
  1267.  
  1268.      whose Taylor series matches the first `2q+1' terms of the Taylor
  1269.      series above; direct evaluation of the Taylor series (with the
  1270.      same preconditioning steps) may be desirable in lieu of the Pade'
  1271.      approximation when `Dq(a)' is ill-conditioned.
  1272.  
  1273. `logm (A)'
  1274.      Compute the matrix logarithm of the square matrix A.  Note that
  1275.      this is currently implemented in terms of an eigenvalue expansion
  1276.      and needs to be improved to be more robust.
  1277.  
  1278. `sqrtm (A)'
  1279.      Compute the matrix square root of the square matrix A.  Note that
  1280.      this is currently implemented in terms of an eigenvalue expansion
  1281.      and needs to be improved to be more robust.
  1282.  
  1283. `kron (A, B)'
  1284.      Form the kronecker product of two matrices, defined block by block
  1285.      as
  1286.  
  1287.           x = [a(i, j) b]
  1288.  
  1289. `qzhess (A, B)'
  1290.      Compute the Hessenberg-triangular decomposition of the matrix
  1291.      pencil `(a, b)'.  This function returns `aa = q * a * z', `bb = q
  1292.      * b * z', `q', `z' orthogonal.  For example,
  1293.  
  1294.           [aa, bb, q, z] = qzhess (a, b)
  1295.  
  1296.      The Hessenberg-triangular decomposition is the first step in Moler
  1297.      and Stewart's QZ decomposition algorithm.  (The QZ decomposition
  1298.      will be included in a later release of Octave.)
  1299.  
  1300.      Algorithm taken from Golub and Van Loan, `Matrix Computations, 2nd
  1301.      edition'.
  1302.  
  1303. `qzval (A, B)'
  1304.      Compute generalized eigenvalues.
  1305.  
  1306. `syl (A, B, C)'
  1307.      Solve the Sylvester equation
  1308.  
  1309.           A X + X B + C = 0
  1310.  
  1311.      using standard LAPACK subroutines.
  1312.  
  1313. 
  1314. File: octave.info,  Node: Polynomial Manipulations,  Next: Nonlinear Equations,  Prev: Linear Algebra,  Up: Top
  1315.  
  1316. Polynomial Manipulations
  1317. ************************
  1318.  
  1319.    In Octave, a polynomial is represented by its coefficients (arranged
  1320. in descending order).  For example, a vector C of length N+1
  1321. corresponds to the following N-th order polynomial
  1322.  
  1323.      p(x) = c(1) x^n + ... + c(n) x + c(n+1).
  1324.  
  1325. `compan (C)'
  1326.      Compute the companion matrix corresponding to polynomial
  1327.      coefficient vector C.
  1328.  
  1329.      The companion matrix is
  1330.  
  1331.                _                                                        _
  1332.               |  -c(2)/c(1)   -c(3)/c(1)  ...  -c(n)/c(1)  -c(n+1)/c(1)  |
  1333.               |       1            0      ...       0             0      |
  1334.               |       0            1      ...       0             0      |
  1335.           A = |       .            .   .            .             .      |
  1336.               |       .            .       .        .             .      |
  1337.               |       .            .           .    .             .      |
  1338.               |_      0            0      ...       1             0     _|
  1339.  
  1340.      The eigenvalues of the companion matrix are equal to the roots of
  1341.      the polynomial.
  1342.  
  1343. `conv (A, B)'
  1344.      Convolve two vectors.
  1345.  
  1346.      `y = conv (a, b)' returns a vector of length equal to `length (a)
  1347.      + length (b) - 1'.  If A and B are polynomial coefficient vectors,
  1348.      `conv' returns the coefficients of the product polynomial.
  1349.  
  1350. `deconv (Y, A)'
  1351.      Deconvolve two vectors.
  1352.  
  1353.      `[b, r] = deconv (y, a)' solves for B and R such that `y = conv
  1354.      (a, b) + r'.
  1355.  
  1356.      If Y and A are polynomial coefficient vectors, B will contain the
  1357.      coefficients of the polynomial quotient and R will be a remander
  1358.      polynomial of lowest order.
  1359.  
  1360. `poly (A)'
  1361.      If A is a square N-by-N matrix, `poly (A)' is the row vector of
  1362.      the coefficients of `det (z * eye (n) - a)', the characteristic
  1363.      polynomial of A.  If X is a vector, `poly (X)' is a vector of
  1364.      coefficients of the polynomial whose roots are the elements of X.
  1365.  
  1366. `polyderiv (C)'
  1367.      Returns the coefficients of the derivative of the polynomial whose
  1368.      coefficients are given by vector C.
  1369.  
  1370. `polyinteg (C)'
  1371.      Returns the coefficients of the integral the polynomial whose
  1372.      coefficients are represented by the vector C.
  1373.  
  1374.      The constant of integration is set to zero.
  1375.  
  1376. `polyreduce (C)'
  1377.      Reduces a polynomial coefficient vector to a minimum number of
  1378.      terms by stripping off any leading zeros.
  1379.  
  1380. `polyval (C, X)'
  1381.      Evaluate a polynomial.
  1382.  
  1383.      `polyval (C, X)' will evaluate the polynomial at the specified
  1384.      value of X.
  1385.  
  1386.      If X is a vector or matrix, the polynomial is evaluated at each of
  1387.      the elements of X.
  1388.  
  1389. `polyvalm (C, X)'
  1390.      Evaluate a polynomial in the matrix sense.
  1391.  
  1392.      `polyvalm (C, X)' will evaluate the polynomial in the matrix
  1393.      sense, i.e. matrix multiplication is used instead of element by
  1394.      element multiplication as is used in polyval.
  1395.  
  1396.      The argument X must be a square matrix.
  1397.  
  1398. `residue (B, A, TOL)'
  1399.      If B and A are vectors of polynomial coefficients, then residue
  1400.      calculates the partial fraction expansion corresponding to the
  1401.      ratio of the two polynomials.
  1402.  
  1403.      The function `residue' returns R, P, K, and E, where the vector R
  1404.      contains the residue terms, P contains the pole values, K contains
  1405.      the coefficients of a direct polynomial term (if it exists) and E
  1406.      is a vector containing the powers of the denominators in the
  1407.      partial fraction terms.
  1408.  
  1409.      Assuming B and A represent polynomials  P (s) and Q(s)  we have:
  1410.  
  1411.            P(s)    M       r(m)         N
  1412.            ---- = SUM -------------  + SUM k(n)*s^(N-n)
  1413.            Q(s)   m=1 (s-p(m))^e(m)    n=1
  1414.  
  1415.      where M is the number of poles (the length of the R, P, and E
  1416.      vectors) and N is the length of the K vector.
  1417.  
  1418.      The argument TOL is optional, and if not specified, a default
  1419.      value of 0.001 is assumed.  The tolerance value is used to
  1420.      determine whether poles with small imaginary components are
  1421.      declared real.  It is also used to determine if two poles are
  1422.      distinct.  If the ratio of the imaginary part of a pole to the
  1423.      real part is less than TOL, the imaginary part is discarded.  If
  1424.      two poles are farther apart than TOL they are distinct.  For
  1425.      example,
  1426.  
  1427.      Example:
  1428.  
  1429.            b = [1, 1, 1];
  1430.            a = [1, -5, 8, -4];
  1431.           
  1432.            [r, p, k, e] = residue (b, a)
  1433.  
  1434.      returns
  1435.  
  1436.           r = [-2, 7, 3]
  1437.           
  1438.           p = [2, 2, 1]
  1439.           
  1440.           k = [](0x0)
  1441.           
  1442.           e = [1, 2, 1]
  1443.  
  1444.      which implies the following partial fraction expansion
  1445.  
  1446.                   s^2 + s + 1       -2        7        3
  1447.              ------------------- = ----- + ------- + -----
  1448.              s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)
  1449.  
  1450. `roots (V)'
  1451.      For a vector V with N components, return the roots of the
  1452.      polynomial
  1453.  
  1454.           v(1) * z^(n-1) + ... + v(n-1) * z + v(n).
  1455.  
  1456. 
  1457. File: octave.info,  Node: Nonlinear Equations,  Next: Differential Equations,  Prev: Polynomial Manipulations,  Up: Top
  1458.  
  1459. Nonlinear Equations
  1460. *******************
  1461.  
  1462.    Octave can solve sets of nonlinear equations of the form
  1463.  
  1464.      F (x) = 0
  1465.  
  1466. using the function `fsolve', which is based on the MINPACK subroutine
  1467. `hybrd'.
  1468.  
  1469.    For example, to solve the set of equations
  1470.  
  1471.      -2x^2 + 3xy   + 4 sin(y) = 6
  1472.       3x^2 - 2xy^2 + 3 cos(x) = -4
  1473.  
  1474. you first need to write a function to compute the value of the given
  1475. function.  For example:
  1476.  
  1477.      function y = f (x)
  1478.      
  1479.        y(1) = -2*x(1)^2 + 3*x(1)*x(2)   + 4*sin(x(2)) - 6;
  1480.        y(2) =  3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4;
  1481.      
  1482.      endfunction
  1483.  
  1484.    Then, call `fsolve' with a specified initial condition to find the
  1485. roots of the system of equations.  For example, given the function `f'
  1486. defined above,
  1487.  
  1488.      [x, info] = fsolve ("f", [1; 2])
  1489.  
  1490. results in the solution
  1491.  
  1492.      x =
  1493.      
  1494.        0.57983
  1495.        2.54621
  1496.      
  1497.      info = 1
  1498.  
  1499.    A value of `info = 1' indicates that the solution has converged.
  1500.  
  1501.    The function `perror' may be used to print English messages
  1502. corresponding to the numeric error codes.  For example,
  1503.  
  1504.      perror ("fsolve", 1)
  1505.  
  1506. prints
  1507.  
  1508.      solution converged to requested tolerance
  1509.  
  1510.    Tolerances and other options for `fsolve' may be specified using the
  1511. function `fsolve_options'.
  1512.  
  1513. 
  1514. File: octave.info,  Node: Differential Equations,  Next: Optimization,  Prev: Nonlinear Equations,  Up: Top
  1515.  
  1516. Differential Equations
  1517. **********************
  1518.  
  1519.    Octave has two built-in functions for solving differential equations.
  1520. Both are based on reliable ODE solvers written in Fortran.
  1521.  
  1522. * Menu:
  1523.  
  1524. * Ordinary Differential Equations::
  1525. * Differential-Algebraic Equations::
  1526.  
  1527.