39 DEFUN (matrix_type, args, ,
41 @deftypefn {Built-in Function} {@var{type} =} matrix_type (@var{A})\n\
42 @deftypefnx {Built-in Function} {@var{type} =} matrix_type (@var{A}, \"nocompute\")\n\
43 @deftypefnx {Built-in Function} {@var{A} =} matrix_type (@var{A}, @var{type})\n\
44 @deftypefnx {Built-in Function} {@var{A} =} matrix_type (@var{A}, \"upper\", @var{perm})\n\
45 @deftypefnx {Built-in Function} {@var{A} =} matrix_type (@var{A}, \"lower\", @var{perm})\n\
46 @deftypefnx {Built-in Function} {@var{A} =} matrix_type (@var{A}, \"banded\", @var{nl}, @var{nu})\n\
47 Identify the matrix type or mark a matrix as a particular type. This allows\n\
48 more rapid solutions of linear equations involving @var{A} to be performed.\n\
49 Called with a single argument, @code{matrix_type} returns the type of the\n\
50 matrix and caches it for future use. Called with more than one argument,\n\
51 @code{matrix_type} allows the type of the matrix to be defined.\n\
53 If the option @qcode{\"nocompute\"} is given, the function will not attempt\n\
54 to guess the type if it is still unknown. This is useful for debugging\n\
57 The possible matrix types depend on whether the matrix is full or sparse, and\n\
58 can be one of the following\n\
61 @item @qcode{\"unknown\"}\n\
62 Remove any previously cached matrix type, and mark type as unknown.\n\
64 @item @qcode{\"full\"}\n\
65 Mark the matrix as full.\n\
67 @item @qcode{\"positive definite\"}\n\
68 Probable full positive definite matrix.\n\
70 @item @qcode{\"diagonal\"}\n\
71 Diagonal matrix. (Sparse matrices only)\n\
73 @item @qcode{\"permuted diagonal\"}\n\
74 Permuted Diagonal matrix. The permutation does not need to be specifically\n\
75 indicated, as the structure of the matrix explicitly gives this. (Sparse\n\
78 @item @qcode{\"upper\"}\n\
79 Upper triangular. If the optional third argument @var{perm} is given, the\n\
80 matrix is assumed to be a permuted upper triangular with the permutations\n\
81 defined by the vector @var{perm}.\n\
83 @item @qcode{\"lower\"}\n\
84 Lower triangular. If the optional third argument @var{perm} is given, the\n\
85 matrix is assumed to be a permuted lower triangular with the permutations\n\
86 defined by the vector @var{perm}.\n\
88 @item @qcode{\"banded\"}\n\
89 @itemx @qcode{\"banded positive definite\"}\n\
90 Banded matrix with the band size of @var{nl} below the diagonal and @var{nu}\n\
91 above it. If @var{nl} and @var{nu} are 1, then the matrix is tridiagonal and\n\
92 treated with specialized code. In addition the matrix can be marked as\n\
93 probably a positive definite. (Sparse matrices only)\n\
95 @item @qcode{\"singular\"}\n\
96 The matrix is assumed to be singular and will be treated with a minimum norm\n\
101 Note that the matrix type will be discovered automatically on the first\n\
102 attempt to solve a linear equation involving @var{A}. Therefore\n\
103 @code{matrix_type} is only useful to give Octave hints of the matrix type.\n\
104 Incorrectly defining the matrix type will result in incorrect results from\n\
105 solutions of linear equations; it is entirely @strong{the responsibility of\n\
106 the user} to correctly identify the matrix type.\n\
108 Also, the test for positive definiteness is a low-cost test for a Hermitian\n\
109 matrix with a real positive diagonal. This does not guarantee that the\n\
110 matrix is positive definite, but only that it is a probable candidate. When\n\
111 such a matrix is factorized, a Cholesky@tie{}factorization is first\n\
112 attempted, and if that fails the matrix is then treated with an\n\
113 LU@tie{}factorization. Once the matrix has been factorized,\n\
114 @code{matrix_type} will return the correct classification of the matrix.\n\
117 int nargin = args.length ();
123 error (
"matrix_type: incorrect number of arguments");
126 bool autocomp =
true;
127 if (nargin == 2 && args(1).is_string ()
128 && args(1).string_value () ==
"nocompute")
134 if (args(0).is_scalar_type ())
141 else if (args(0).is_sparse_type ())
147 if (args(0).is_complex_type ())
154 args(0).sparse_complex_matrix_value ();
158 args(0).matrix_type (mattyp);
172 args(0).matrix_type (mattyp);
177 int typ = mattyp.
type ();
198 retval =
octave_value (
"Tridiagonal Positive Definite");
203 if (args(0).rows () == args(0).columns ())
216 std::string str_typ = args(1).string_value ();
225 error (
"matrix_type: TYPE must be a string");
230 str_typ.begin (), tolower);
232 if (str_typ ==
"diagonal")
234 if (str_typ ==
"permuted diagonal")
236 else if (str_typ ==
"upper")
238 else if (str_typ ==
"lower")
240 else if (str_typ ==
"banded"
241 || str_typ ==
"banded positive definite")
244 error (
"matrix_type: banded matrix type requires 4 arguments");
247 nl = args(2).nint_value ();
248 nu = args(3).nint_value ();
251 error (
"matrix_type: band size NL, NU must be integers");
254 if (nl == 1 && nu == 1)
259 if (str_typ ==
"banded positive definite")
264 else if (str_typ ==
"positive definite")
269 else if (str_typ ==
"singular")
271 else if (str_typ ==
"full")
273 else if (str_typ ==
"unknown")
276 error (
"matrix_type: Unknown matrix type %s", str_typ.c_str ());
281 && (str_typ ==
"upper" || str_typ ==
"lower"))
287 error (
"matrix_type: Invalid permutation vector PERM");
294 error (
"matrix_type: Invalid permutation vector PERM");
300 p[i] = static_cast<octave_idx_type>
304 if (str_typ ==
"upper")
312 && str_typ !=
"banded positive definite"
313 && str_typ !=
"banded")
314 error (
"matrix_type: Invalid number of arguments");
319 if (args(0).is_complex_type ())
338 if (args(0).is_complex_type ())
344 if (args(0).is_single_type ())
347 m = args(0).float_complex_matrix_value ();
351 args(0).matrix_type (mattyp);
360 args(0).matrix_type (mattyp);
371 if (args(0).is_single_type ())
377 args(0).matrix_type (mattyp);
382 Matrix m = args(0).matrix_value ();
386 args(0).matrix_type (mattyp);
392 int typ = mattyp.
type ();
406 if (args(0).rows () == args(0).columns ())
419 std::string str_typ = args(1).string_value ();
425 error (
"matrix_type: TYPE must be a string");
430 str_typ.begin (), tolower);
432 if (str_typ ==
"upper")
434 else if (str_typ ==
"lower")
436 else if (str_typ ==
"positive definite")
441 else if (str_typ ==
"singular")
443 else if (str_typ ==
"full")
445 else if (str_typ ==
"unknown")
448 error (
"matrix_type: Unknown matrix type %s",
453 if (nargin == 3 && (str_typ ==
"upper"
454 || str_typ ==
"lower"))
460 error (
"matrix_type: Invalid permutation vector PERM");
467 error (
"matrix_type: Invalid permutation vector PERM");
473 p[i] = static_cast<octave_idx_type>
477 if (str_typ ==
"upper")
484 else if (nargin != 2)
485 error (
"matrix_type: Invalid number of arguments");
490 if (args(0).is_single_type ())
492 if (args(0).is_complex_type ())
494 (args(0).float_complex_matrix_value (),
498 (args(0).float_matrix_value (),
503 if (args(0).is_complex_type ())
505 (args(0).complex_matrix_value (),
509 (args(0).matrix_value (),