49 DEFUN (balance, args, nargout,
51 @deftypefn {Built-in Function} {@var{AA} =} balance (@var{A})\n\
52 @deftypefnx {Built-in Function} {@var{AA} =} balance (@var{A}, @var{opt})\n\
53 @deftypefnx {Built-in Function} {[@var{DD}, @var{AA}] =} balance (@var{A}, @var{opt})\n\
54 @deftypefnx {Built-in Function} {[@var{D}, @var{P}, @var{AA}] =} balance (@var{A}, @var{opt})\n\
55 @deftypefnx {Built-in Function} {[@var{CC}, @var{DD}, @var{AA}, @var{BB}] =} balance (@var{A}, @var{B}, @var{opt})\n\
57 Balance the matrix @var{A} to reduce numerical errors in future\n\
60 Compute @code{@var{AA} = @var{DD} \\ @var{A} * @var{DD}} in which @var{AA}\n\
61 is a matrix whose row and column norms are roughly equal in magnitude, and\n\
62 @code{@var{DD} = @var{P} * @var{D}}, in which @var{P} is a permutation\n\
63 matrix and @var{D} is a diagonal matrix of powers of two. This allows the\n\
64 equilibration to be computed without round-off. Results of eigenvalue\n\
65 calculation are typically improved by balancing first.\n\
67 If two output values are requested, @code{balance} returns\n\
68 the diagonal @var{D} and the permutation @var{P} separately as vectors.\n\
69 In this case, @code{@var{DD} = eye(n)(:,@var{P}) * diag (@var{D})}, where\n\
70 @math{n} is the matrix size.\n\
72 If four output values are requested, compute @code{@var{AA} =\n\
73 @var{CC}*@var{A}*@var{DD}} and @code{@var{BB} = @var{CC}*@var{B}*@var{DD}},\n\
74 in which @var{AA} and @var{BB} have nonzero elements of approximately the\n\
75 same magnitude and @var{CC} and @var{DD} are permuted diagonal matrices as\n\
76 in @var{DD} for the algebraic eigenvalue problem.\n\
78 The eigenvalue balancing option @var{opt} may be one of:\n\
81 @item @qcode{\"noperm\"}, @qcode{\"S\"}\n\
82 Scale only; do not permute.\n\
84 @item @qcode{\"noscal\"}, @qcode{\"P\"}\n\
85 Permute only; do not scale.\n\
88 Algebraic eigenvalue balancing uses standard @sc{lapack} routines.\n\
90 Generalized eigenvalue problem balancing uses Ward's algorithm\n\
91 (SIAM Journal on Scientific and Statistical Computing, 1981).\n\
96 int nargin = args.
length ();
98 if (nargin < 1 || nargin > 3 || nargout < 0 || nargout > 4)
105 bool AEPcase = nargin == 1 || args(1).is_string ();
110 if (nn != args(0).columns ())
116 bool isfloat = args(0).is_single_type ()
117 || (! AEPcase && args(1).is_single_type ());
119 bool complex_case = args(0).is_complex_type ()
120 || (! AEPcase && args(1).is_complex_type ());
131 fcaa = args(0).float_complex_matrix_value ();
133 faa = args(0).float_matrix_value ();
138 caa = args(0).complex_matrix_value ();
140 aa = args(0).matrix_value ();
154 std::string a1s = args(1).string_value ();
155 noperm = a1s ==
"noperm" || a1s ==
"S";
156 noscal = a1s ==
"noscal" || a1s ==
"P";
166 if (nargout == 0 || nargout == 1)
168 else if (nargout == 2)
185 if (nargout == 0 || nargout == 1)
187 else if (nargout == 2)
206 if (nargout == 0 || nargout == 1)
208 else if (nargout == 2)
224 if (nargout == 0 || nargout == 1)
226 else if (nargout == 2)
244 warning (
"balance: used GEP, should have two output arguments");
249 else if (args(2).is_string ())
250 bal_job = args(2).string_value ();
253 error (
"balance: OPT argument must be a string");
257 if ((nn != args(1).columns ()) || (nn != args(1).rows ()))
271 fcbb = args(1).float_complex_matrix_value ();
273 fbb = args(1).float_matrix_value ();
278 cbb = args(1).complex_matrix_value ();
280 bb = args(1).matrix_value ();
307 error (
"balance: invalid number of output arguments");
332 error (
"balance: invalid number of output arguments");
360 error (
"balance: invalid number of output arguments");
385 error (
"balance: invalid number of output arguments");
void gripe_nonconformant(const char *op, octave_idx_type op1_len, octave_idx_type op2_len)
OCTINTERP_API void print_usage(void)
static octave_idx_type nn
octave_idx_type length(void) const
FloatMatrix balancing_matrix2(void) const
#define DEFUN(name, args_name, nargout_name, doc)
void error(const char *fmt,...)
FloatComplexMatrix balanced_matrix2(void) const
FloatMatrix balancing_matrix(void) const
void gripe_square_matrix_required(const char *name)
Matrix balanced_matrix2(void) const
FloatMatrix balancing_matrix2(void) const
Matrix balancing_matrix(void) const
Matrix balancing_matrix(void) const
FloatMatrix balanced_matrix2(void) const
Matrix balancing_matrix2(void) const
VectorT scaling_vector(void) const
Matrix balanced_matrix(void) const
FloatMatrix balancing_matrix(void) const
ComplexMatrix balanced_matrix2(void) const
FloatComplexMatrix balancing_matrix(void) const
void warning(const char *fmt,...)
VectorT permuting_vector(void) const
Matrix balancing_matrix(void) const
FloatComplexMatrix balanced_matrix(void) const
FloatMatrix balancing_matrix(void) const
ComplexMatrix balanced_matrix(void) const
MatrixT balanced_matrix(void) const
FloatMatrix balanced_matrix(void) const
Matrix balancing_matrix2(void) const
ComplexMatrix balancing_matrix(void) const