GNU Octave  4.4.1
A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab
hess.cc
Go to the documentation of this file.
1 /*
2 
3 Copyright (C) 1996-2018 John W. Eaton
4 
5 This file is part of Octave.
6 
7 Octave is free software: you can redistribute it and/or modify it
8 under the terms of the GNU General Public License as published by
9 the Free Software Foundation, either version 3 of the License, or
10 (at your option) any later version.
11 
12 Octave is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16 
17 You should have received a copy of the GNU General Public License
18 along with Octave; see the file COPYING. If not, see
19 <https://www.gnu.org/licenses/>.
20 
21 */
22 
23 #if defined (HAVE_CONFIG_H)
24 # include "config.h"
25 #endif
26 
27 #include "hess.h"
28 
29 #include "defun.h"
30 #include "error.h"
31 #include "errwarn.h"
32 #include "ovl.h"
33 
34 DEFUN (hess, args, nargout,
35  doc: /* -*- texinfo -*-
36 @deftypefn {} {@var{H} =} hess (@var{A})
37 @deftypefnx {} {[@var{P}, @var{H}] =} hess (@var{A})
38 @cindex Hessenberg decomposition
39 Compute the Hessenberg decomposition of the matrix @var{A}.
40 
41 The Hessenberg decomposition is
42 @tex
43 $$
44 A = PHP^T
45 $$
46 where $P$ is a square unitary matrix ($P^TP = I$), and $H$
47 is upper Hessenberg ($H_{i,j} = 0, \forall i > j+1$).
48 @end tex
49 @ifnottex
50 @code{@var{P} * @var{H} * @var{P}' = @var{A}} where @var{P} is a square
51 unitary matrix (@code{@var{P}' * @var{P} = I}, using complex-conjugate
52 transposition) and @var{H} is upper Hessenberg
53 (@code{@var{H}(i, j) = 0 forall i > j+1)}.
54 @end ifnottex
55 
56 The Hessenberg decomposition is usually used as the first step in an
57 eigenvalue computation, but has other applications as well
58 (see @nospell{Golub, Nash, and Van Loan},
59 IEEE Transactions on Automatic Control, 1979).
60 @seealso{eig, chol, lu, qr, qz, schur, svd}
61 @end deftypefn */)
62 {
63  if (args.length () != 1)
64  print_usage ();
65 
66  octave_value arg = args(0);
67 
68  if (arg.isempty ())
69  return octave_value_list (2, Matrix ());
70 
71  if (arg.rows () != arg.columns ())
72  err_square_matrix_required ("hess", "A");
73 
75 
76  if (arg.is_single_type ())
77  {
78  if (arg.isreal ())
79  {
81 
83 
84  if (nargout <= 1)
85  retval = ovl (result.hess_matrix ());
86  else
87  retval = ovl (result.unitary_hess_matrix (),
88  result.hess_matrix ());
89  }
90  else if (arg.iscomplex ())
91  {
93 
95 
96  if (nargout <= 1)
97  retval = ovl (result.hess_matrix ());
98  else
99  retval = ovl (result.unitary_hess_matrix (),
100  result.hess_matrix ());
101  }
102  }
103  else
104  {
105  if (arg.isreal ())
106  {
107  Matrix tmp = arg.matrix_value ();
108 
110 
111  if (nargout <= 1)
112  retval = ovl (result.hess_matrix ());
113  else
114  retval = ovl (result.unitary_hess_matrix (),
115  result.hess_matrix ());
116  }
117  else if (arg.iscomplex ())
118  {
120 
122 
123  if (nargout <= 1)
124  retval = ovl (result.hess_matrix ());
125  else
126  retval = ovl (result.unitary_hess_matrix (),
127  result.hess_matrix ());
128  }
129  else
130  err_wrong_type_arg ("hess", arg);
131  }
132 
133  return retval;
134 }
135 
136 /*
137 %!test
138 %! a = [1, 2, 3; 5, 4, 6; 8, 7, 9];
139 %! [p, h] = hess (a);
140 %! assert (p * h * p', a, sqrt (eps));
141 
142 %!test
143 %! a = single ([1, 2, 3; 5, 4, 6; 8, 7, 9]);
144 %! [p, h] = hess (a);
145 %! assert (p * h * p', a, sqrt (eps ("single")));
146 
147 %!error hess ()
148 %!error hess ([1, 2; 3, 4], 2)
149 %!error <must be a square matrix> hess ([1, 2; 3, 4; 5, 6])
150 */
bool isempty(void) const
Definition: ov.h:529
OCTINTERP_API void print_usage(void)
Definition: defun.cc:54
#define DEFUN(name, args_name, nargout_name, doc)
Macro to define a builtin function.
Definition: defun.h:53
FloatMatrix float_matrix_value(bool frc_str_conv=false) const
Definition: ov.h:837
void err_square_matrix_required(const char *fcn, const char *name)
Definition: errwarn.cc:118
octave_value arg
Definition: pr-output.cc:3244
FloatComplexMatrix float_complex_matrix_value(bool frc_str_conv=false) const
Definition: ov.h:856
OCTAVE_EXPORT octave_value_list return the number of command line arguments passed to Octave If called with the optional argument the function xample nargout(@histc)
Definition: ov-usr-fcn.cc:997
octave_idx_type columns(void) const
Definition: ov.h:474
bool is_single_type(void) const
Definition: ov.h:651
octave_idx_type rows(void) const
Definition: ov.h:472
double tmp
Definition: data.cc:6252
octave_value retval
Definition: data.cc:6246
Definition: dMatrix.h:36
void err_wrong_type_arg(const char *name, const char *s)
Definition: errwarn.cc:162
With real return the complex result
Definition: data.cc:3260
bool isreal(void) const
Definition: ov.h:703
OCTAVE_EXPORT octave_value_list isa nd deftypefn *return ovl(args(0).isinteger())
bool iscomplex(void) const
Definition: ov.h:710
ComplexMatrix complex_matrix_value(bool frc_str_conv=false) const
Definition: ov.h:852
Definition: mx-defs.h:71
Matrix matrix_value(bool frc_str_conv=false) const
Definition: ov.h:834