octave_packages/m/polynomial/compan.m

   1 ## Copyright (C) 1994-2012 John W. Eaton
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn {Function File} {} compan (@var{c})
  21 ## Compute the companion matrix corresponding to polynomial coefficient
  22 ## vector @var{c}.
  23 ##
  24 ## The companion matrix is
  25 ## @tex
  26 ## $$
  27 ## A = \left[\matrix{
  28 ##  -c_2/c_1 & -c_3/c_1 & \cdots & -c_N/c_1 & -c_{N+1}/c_1\cr
  29 ##      1    &     0    & \cdots &     0    &         0   \cr
  30 ##      0    &     1    & \cdots &     0    &         0   \cr
  31 ##   \vdots  &   \vdots & \ddots &  \vdots  &      \vdots \cr
  32 ##      0    &     0    & \cdots &     1    &         0}\right].
  33 ## $$
  34 ## @end tex
  35 ## @ifnottex
  36 ## @c Set example in small font to prevent overfull line
  37 ##
  38 ## @smallexample
  39 ## @group
  40 ##      _                                                        _
  41 ##     |  -c(2)/c(1)   -c(3)/c(1)  @dots{}  -c(N)/c(1)  -c(N+1)/c(1)  |
  42 ##     |       1            0      @dots{}       0             0      |
  43 ##     |       0            1      @dots{}       0             0      |
  44 ## A = |       .            .      .         .             .      |
  45 ##     |       .            .       .        .             .      |
  46 ##     |       .            .        .       .             .      |
  47 ##     |_      0            0      @dots{}       1             0     _|
  48 ## @end group
  49 ## @end smallexample
  50 ##
  51 ## @end ifnottex
  52 ## The eigenvalues of the companion matrix are equal to the roots of the
  53 ## polynomial.
  54 ## @seealso{roots, poly, eig}
  55 ## @end deftypefn
  56
  57 ## Author: Tony Richardson <arichard@stark.cc.oh.us>
  58 ## Created: June 1994
  59 ## Adapted-By: jwe
  60
  61 function A = compan (c)
  62
  63   if (nargin != 1)
  64     print_usage ();
  65   endif
  66
  67   if (! isvector (c))
  68     error ("compan: expecting a vector argument");
  69   endif
  70
  71   n = length (c);
  72
  73   if (n == 1)
  74     A = [];
  75   else
  76     A = diag (ones (n-2, 1), -1);
  77     A(1,:) = -c(2:n) / c(1);
  78   endif
  79
  80 endfunction
  81
  82 %!assert(all (all (compan ([1, 2, 3]) == [-2, -3; 1, 0])));
  83
  84 %!assert(all (all (compan ([1; 2; 3]) == [-2, -3; 1, 0])));
  85
  86 %!assert(isempty (compan (4)));
  87
  88 %!assert(all (all (compan ([3, 2, 1]) == [-2/3, -1/3; 1, 0])));
  89
  90 %!error compan ([1,2;3,4]);
  91
  92 %!error compan ([]);
  93