|
2670
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
2333
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
2670
|
5 @node Matrix Manipulation, Arithmetic, Plotting, Top |
|
2333
|
6 @chapter Matrix Manipulation |
|
|
7 |
|
|
8 There are a number of functions available for checking to see if the |
|
|
9 elements of a matrix meet some condition, and for rearranging the |
|
|
10 elements of a matrix. For example, Octave can easily tell you if all |
|
|
11 the elements of a matrix are finite, or are less than some specified |
|
|
12 value. Octave can also rotate the elements, extract the upper- or |
|
|
13 lower-triangular parts, or sort the columns of a matrix. |
|
|
14 |
|
|
15 @menu |
|
|
16 * Finding Elements and Checking Conditions:: |
|
|
17 * Rearranging Matrices:: |
|
2670
|
18 * Special Utility Matrices:: |
|
|
19 * Famous Matrices:: |
|
2333
|
20 @end menu |
|
|
21 |
|
|
22 @node Finding Elements and Checking Conditions, Rearranging Matrices, Matrix Manipulation, Matrix Manipulation |
|
|
23 @section Finding Elements and Checking Conditions |
|
|
24 |
|
|
25 The functions @code{any} and @code{all} are useful for determining |
|
|
26 whether any or all of the elements of a matrix satisfy some condition. |
|
|
27 The @code{find} function is also useful in determining which elements of |
|
|
28 a matrix meet a specified condition. |
|
|
29 |
|
2449
|
30 @deftypefn {Built-in Function} {} any (@var{x}) |
|
|
31 For a vector argument, return 1 if any element of the vector is |
|
|
32 nonzero. |
|
2333
|
33 |
|
2449
|
34 For a matrix argument, return a row vector of ones and |
|
2333
|
35 zeros with each element indicating whether any of the elements of the |
|
|
36 corresponding column of the matrix are nonzero. For example, |
|
|
37 |
|
|
38 @example |
|
2449
|
39 @group |
|
|
40 any (eye (2, 4)) |
|
|
41 @result{} [ 1, 1, 0, 0 ] |
|
|
42 @end group |
|
2333
|
43 @end example |
|
|
44 |
|
|
45 To see if any of the elements of a matrix are nonzero, you can use a |
|
|
46 statement like |
|
|
47 |
|
|
48 @example |
|
|
49 any (any (a)) |
|
|
50 @end example |
|
2449
|
51 @end deftypefn |
|
2333
|
52 |
|
2449
|
53 @deftypefn {Built-in Function} {} all (@var{x}) |
|
2333
|
54 The function @code{all} behaves like the function @code{any}, except |
|
|
55 that it returns true only if all the elements of a vector, or all the |
|
|
56 elements in a column of a matrix, are nonzero. |
|
2449
|
57 @end deftypefn |
|
2333
|
58 |
|
|
59 Since the comparison operators (@pxref{Comparison Ops}) return matrices |
|
|
60 of ones and zeros, it is easy to test a matrix for many things, not just |
|
|
61 whether the elements are nonzero. For example, |
|
|
62 |
|
|
63 @example |
|
2449
|
64 @group |
|
|
65 all (all (rand (5) < 0.9)) |
|
|
66 @result{} 0 |
|
|
67 @end group |
|
2333
|
68 @end example |
|
|
69 |
|
|
70 @noindent |
|
|
71 tests a random 5 by 5 matrix to see if all of it's elements are less |
|
|
72 than 0.9. |
|
|
73 |
|
|
74 Note that in conditional contexts (like the test clause of @code{if} and |
|
|
75 @code{while} statements) Octave treats the test as if you had typed |
|
|
76 @code{all (all (condition))}. |
|
|
77 |
|
2689
|
78 @deftypefn {Function File} {[@var{err}, @var{y1}, ...] =} common_size (@var{x1}, ...) |
|
2541
|
79 Determine if all input arguments are either scalar or of common |
|
2689
|
80 size. If so, @var{err} is zero, and @var{yi} is a matrix of the |
|
|
81 common size with all entries equal to @var{xi} if this is a scalar or |
|
|
82 @var{xi} otherwise. If the inputs cannot be brought to a common size, |
|
|
83 errorcode is 1, and @var{yi} is @var{xi}. For example, |
|
2541
|
84 |
|
|
85 @example |
|
|
86 @group |
|
|
87 [errorcode, a, b] = common_size ([1 2; 3 4], 5) |
|
|
88 @result{} errorcode = 0 |
|
2653
|
89 @result{} a = [ 1, 2; 3, 4 ] |
|
|
90 @result{} b = [ 5, 5; 5, 5 ] |
|
2541
|
91 @end group |
|
|
92 @end example |
|
|
93 |
|
|
94 @noindent |
|
|
95 This is useful for implementing functions where arguments can either |
|
|
96 be scalars or of common size. |
|
|
97 @end deftypefn |
|
|
98 |
|
|
99 @deftypefn {Function File} {} diff (@var{x}, @var{k}) |
|
|
100 If @var{x} is a vector of length @var{n}, @code{diff (@var{x})} is the |
|
|
101 vector of first differences |
|
|
102 @iftex |
|
|
103 @tex |
|
|
104 $x_2 - x_1, \ldots{}, x_n - x_{n-1}$. |
|
|
105 @end tex |
|
|
106 @end iftex |
|
|
107 @ifinfo |
|
|
108 @var{x}(2) - @var{x}(1), @dots{}, @var{x}(n) - @var{x}(n-1). |
|
|
109 @end ifinfo |
|
|
110 |
|
|
111 If @var{x} is a matrix, @code{diff (@var{x})} is the matrix of column |
|
|
112 differences. |
|
|
113 |
|
|
114 The second argument is optional. If supplied, @code{diff (@var{x}, |
|
|
115 @var{k})}, where @var{k} is a nonnegative integer, returns the |
|
|
116 @var{k}-th differences. |
|
|
117 @end deftypefn |
|
|
118 |
|
2449
|
119 @deftypefn {Mapping Function} {} isinf (@var{x}) |
|
|
120 Return 1 for elements of @var{x} that are infinite and zero |
|
|
121 otherwise. For example, |
|
|
122 |
|
|
123 @example |
|
|
124 @group |
|
|
125 isinf ([13, Inf, NaN]) |
|
|
126 @result{} [ 0, 1, 0 ] |
|
|
127 @end group |
|
|
128 @end example |
|
|
129 @end deftypefn |
|
|
130 |
|
|
131 @deftypefn {Mapping Function} {} isnan (@var{x}) |
|
|
132 Return 1 for elements of @var{x} that are NaN values and zero |
|
|
133 otherwise. For example, |
|
2333
|
134 |
|
|
135 @example |
|
2449
|
136 @group |
|
|
137 isnan ([13, Inf, NaN]) |
|
|
138 @result{} [ 0, 0, 1 ] |
|
|
139 @end group |
|
|
140 @end example |
|
|
141 @end deftypefn |
|
|
142 |
|
|
143 @deftypefn {Mapping Function} {} finite (@var{x}) |
|
|
144 Return 1 for elements of @var{x} that are NaN values and zero |
|
|
145 otherwise. For example, |
|
2333
|
146 |
|
|
147 @example |
|
2449
|
148 @group |
|
|
149 finite ([13, Inf, NaN]) |
|
|
150 @result{} [ 1, 0, 0 ] |
|
|
151 @end group |
|
2333
|
152 @end example |
|
2449
|
153 @end deftypefn |
|
2333
|
154 |
|
2465
|
155 @deftypefn {Loadable Function} {} find (@var{x}) |
|
2768
|
156 Return a vector of indices of nonzero elements of a matrix. To obtain a |
|
|
157 single index for each matrix element, Octave pretends that the columns |
|
|
158 of a matrix form one long vector (like Fortran arrays are stored). For |
|
|
159 example, |
|
2333
|
160 |
|
|
161 @example |
|
2449
|
162 @group |
|
|
163 find (eye (2)) |
|
|
164 @result{} [ 1; 4 ] |
|
|
165 @end group |
|
2333
|
166 @end example |
|
|
167 |
|
|
168 If two outputs are requested, @code{find} returns the row and column |
|
|
169 indices of nonzero elements of a matrix. For example, |
|
|
170 |
|
|
171 @example |
|
2449
|
172 @group |
|
|
173 [i, j] = find (2 * eye (2)) |
|
|
174 @result{} i = [ 1; 2 ] |
|
|
175 @result{} j = [ 1; 2 ] |
|
|
176 @end group |
|
2333
|
177 @end example |
|
|
178 |
|
2449
|
179 If three outputs are requested, @code{find} also returns a vector |
|
|
180 containing the the nonzero values. For example, |
|
|
181 |
|
|
182 @example |
|
|
183 @group |
|
|
184 [i, j, v] = find (3 * eye (2)) |
|
|
185 @result{} i = [ 1; 2 ] |
|
|
186 @result{} j = [ 1; 2 ] |
|
|
187 @result{} v = [ 3; 3 ] |
|
|
188 @end group |
|
|
189 @end example |
|
|
190 @end deftypefn |
|
2333
|
191 |
|
2670
|
192 @node Rearranging Matrices, Special Utility Matrices, Finding Elements and Checking Conditions, Matrix Manipulation |
|
2333
|
193 @section Rearranging Matrices |
|
|
194 |
|
2449
|
195 @deftypefn {Function File} {} fliplr (@var{x}) |
|
|
196 Return a copy of @var{x} with the order of the columns reversed. For |
|
|
197 example, |
|
|
198 |
|
|
199 @example |
|
|
200 @group |
|
|
201 fliplr ([1, 2; 3, 4]) |
|
|
202 @result{} 2 1 |
|
|
203 4 3 |
|
|
204 @end group |
|
|
205 @end example |
|
|
206 @end deftypefn |
|
|
207 |
|
|
208 @deftypefn {Function File} {} flipud (@var{x}) |
|
|
209 Return a copy of @var{x} with the order of the rows reversed. For |
|
|
210 example, |
|
2333
|
211 |
|
|
212 @example |
|
2449
|
213 @group |
|
|
214 flipud ([1, 2; 3, 4]) |
|
|
215 @result{} 3 4 |
|
|
216 1 2 |
|
|
217 @end group |
|
2333
|
218 @end example |
|
2449
|
219 @end deftypefn |
|
2333
|
220 |
|
2449
|
221 @deftypefn {Function File} {} rot90 (@var{x}, @var{n}) |
|
2768
|
222 Return a copy of @var{x} with the elements rotated counterclockwise in |
|
2449
|
223 90-degree increments. The second argument is optional, and specifies |
|
|
224 how many 90-degree rotations are to be applied (the default value is 1). |
|
|
225 Negative values of @var{n} rotate the matrix in a clockwise direction. |
|
|
226 For example, |
|
2333
|
227 |
|
|
228 @example |
|
2449
|
229 @group |
|
2333
|
230 rot90 ([1, 2; 3, 4], -1) |
|
2449
|
231 @result{} 3 1 |
|
|
232 4 2 |
|
|
233 @end group |
|
2333
|
234 @end example |
|
|
235 |
|
|
236 @noindent |
|
|
237 rotates the given matrix clockwise by 90 degrees. The following are all |
|
|
238 equivalent statements: |
|
|
239 |
|
|
240 @example |
|
2449
|
241 @group |
|
2333
|
242 rot90 ([1, 2; 3, 4], -1) |
|
2653
|
243 @equiv{} |
|
2333
|
244 rot90 ([1, 2; 3, 4], 3) |
|
2653
|
245 @equiv{} |
|
2333
|
246 rot90 ([1, 2; 3, 4], 7) |
|
2449
|
247 @end group |
|
2333
|
248 @end example |
|
2449
|
249 @end deftypefn |
|
2333
|
250 |
|
2449
|
251 @deftypefn {Function File} {} reshape (@var{a}, @var{m}, @var{n}) |
|
|
252 Return a matrix with @var{m} rows and @var{n} columns whose elements are |
|
|
253 taken from the matrix @var{a}. To decide how to order the elements, |
|
|
254 Octave pretends that the elements of a matrix are stored in column-major |
|
|
255 order (like Fortran arrays are stored). |
|
2333
|
256 |
|
|
257 For example, |
|
|
258 |
|
|
259 @example |
|
2449
|
260 @group |
|
|
261 reshape ([1, 2, 3, 4], 2, 2) |
|
|
262 @result{} 1 3 |
|
|
263 2 4 |
|
|
264 @end group |
|
2333
|
265 @end example |
|
|
266 |
|
2449
|
267 If the variable @code{do_fortran_indexing} is nonzero, the |
|
2333
|
268 @code{reshape} function is equivalent to |
|
|
269 |
|
|
270 @example |
|
2449
|
271 @group |
|
2333
|
272 retval = zeros (m, n); |
|
|
273 retval (:) = a; |
|
2449
|
274 @end group |
|
2333
|
275 @end example |
|
|
276 |
|
|
277 @noindent |
|
|
278 but it is somewhat less cryptic to use @code{reshape} instead of the |
|
|
279 colon operator. Note that the total number of elements in the original |
|
|
280 matrix must match the total number of elements in the new matrix. |
|
2449
|
281 @end deftypefn |
|
2333
|
282 |
|
2541
|
283 @deftypefn {Function File} {} shift (@var{x}, @var{b}) |
|
|
284 If @var{x} is a vector, perform a circular shift of length @var{b} of |
|
|
285 the elements of @var{x}. |
|
|
286 |
|
|
287 If @var{x} is a matrix, do the same for each column of @var{x}. |
|
|
288 @end deftypefn |
|
|
289 |
|
2759
|
290 @deftypefn {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}) |
|
2768
|
291 Return a copy of @var{x} with the elements elements arranged in |
|
2449
|
292 increasing order. For matrices, @code{sort} orders the elements in each |
|
|
293 column. |
|
2333
|
294 |
|
|
295 For example, |
|
|
296 |
|
|
297 @example |
|
2449
|
298 @group |
|
|
299 sort ([1, 2; 2, 3; 3, 1]) |
|
|
300 @result{} 1 1 |
|
|
301 2 2 |
|
|
302 3 3 |
|
|
303 @end group |
|
2333
|
304 @end example |
|
|
305 |
|
|
306 The @code{sort} function may also be used to produce a matrix |
|
|
307 containing the original row indices of the elements in the sorted |
|
|
308 matrix. For example, |
|
|
309 |
|
|
310 @example |
|
2449
|
311 @group |
|
|
312 [s, i] = sort ([1, 2; 2, 3; 3, 1]) |
|
|
313 @result{} s = 1 1 |
|
|
314 2 2 |
|
|
315 3 3 |
|
|
316 @result{} i = 1 3 |
|
|
317 2 1 |
|
|
318 3 2 |
|
|
319 @end group |
|
2333
|
320 @end example |
|
2449
|
321 @end deftypefn |
|
2333
|
322 |
|
2449
|
323 Since the @code{sort} function does not allow sort keys to be specified, |
|
2993
|
324 it can't be used to order the rows of a matrix according to the values |
|
|
325 of the elements in various columns@footnote{For example, to first sort |
|
|
326 based on the values in column 1, and then, for any values that are |
|
2333
|
327 repeated in column 1, sort based on the values found in column 2, etc.} |
|
|
328 in a single call. Using the second output, however, it is possible to |
|
|
329 sort all rows based on the values in a given column. Here's an example |
|
2449
|
330 that sorts the rows of a matrix based on the values in the second |
|
|
331 column. |
|
2333
|
332 |
|
|
333 @example |
|
2449
|
334 @group |
|
|
335 a = [1, 2; 2, 3; 3, 1]; |
|
|
336 [s, i] = sort (a (:, 2)); |
|
|
337 a (i, :) |
|
|
338 @result{} 3 1 |
|
|
339 1 2 |
|
|
340 2 3 |
|
|
341 @end group |
|
2333
|
342 @end example |
|
|
343 |
|
2449
|
344 @deftypefn {Function File} {} tril (@var{a}, @var{k}) |
|
|
345 @deftypefnx {Function File} {} triu (@var{a}, @var{k}) |
|
2759
|
346 Return a new matrix formed by extracting extract the lower (@code{tril}) |
|
2449
|
347 or upper (@code{triu}) triangular part of the matrix @var{a}, and |
|
|
348 setting all other elements to zero. The second argument is optional, |
|
|
349 and specifies how many diagonals above or below the main diagonal should |
|
|
350 also be set to zero. |
|
2333
|
351 |
|
|
352 The default value of @var{k} is zero, so that @code{triu} and |
|
|
353 @code{tril} normally include the main diagonal as part of the result |
|
|
354 matrix. |
|
|
355 |
|
|
356 If the value of @var{k} is negative, additional elements above (for |
|
|
357 @code{tril}) or below (for @code{triu}) the main diagonal are also |
|
|
358 selected. |
|
|
359 |
|
|
360 The absolute value of @var{k} must not be greater than the number of |
|
|
361 sub- or super-diagonals. |
|
|
362 |
|
|
363 For example, |
|
|
364 |
|
|
365 @example |
|
|
366 @group |
|
2449
|
367 tril (ones (3), -1) |
|
|
368 @result{} 0 0 0 |
|
|
369 1 0 0 |
|
|
370 1 1 0 |
|
2333
|
371 @end group |
|
|
372 @end example |
|
|
373 |
|
|
374 @noindent |
|
2449
|
375 and |
|
2333
|
376 |
|
|
377 @example |
|
|
378 @group |
|
2449
|
379 tril (ones (3), 1) |
|
|
380 @result{} 1 1 0 |
|
|
381 1 1 1 |
|
|
382 1 1 1 |
|
2333
|
383 @end group |
|
|
384 @end example |
|
2449
|
385 @end deftypefn |
|
2541
|
386 |
|
|
387 @deftypefn {Function File} {} vec (@var{x}) |
|
2768
|
388 Return the vector obtained by stacking the columns of the matrix @var{x} |
|
|
389 one above the other. |
|
2541
|
390 @end deftypefn |
|
|
391 |
|
|
392 @deftypefn {Function File} {} vech (@var{x}) |
|
2768
|
393 Return the vector obtained by eliminating all supradiagonal elements of |
|
|
394 the square matrix @var{x} and stacking the result one column above the |
|
|
395 other. |
|
2541
|
396 @end deftypefn |
|
2670
|
397 |
|
|
398 @node Special Utility Matrices, Famous Matrices, Rearranging Matrices, Matrix Manipulation |
|
|
399 @section Special Utility Matrices |
|
|
400 |
|
|
401 @deftypefn {Built-in Function} {} eye (@var{x}) |
|
|
402 @deftypefnx {Built-in Function} {} eye (@var{n}, @var{m}) |
|
2768
|
403 Return an identity matrix. If invoked with a single scalar argument, |
|
2670
|
404 @code{eye} returns a square matrix with the dimension specified. If you |
|
|
405 supply two scalar arguments, @code{eye} takes them to be the number of |
|
|
406 rows and columns. If given a vector with two elements, @code{eye} uses |
|
|
407 the values of the elements as the number of rows and columns, |
|
2689
|
408 respectively. For example, |
|
2670
|
409 |
|
|
410 @example |
|
|
411 @group |
|
|
412 eye (3) |
|
|
413 @result{} 1 0 0 |
|
|
414 0 1 0 |
|
|
415 0 0 1 |
|
|
416 @end group |
|
|
417 @end example |
|
|
418 |
|
|
419 The following expressions all produce the same result: |
|
|
420 |
|
|
421 @example |
|
|
422 @group |
|
|
423 eye (2) |
|
|
424 @equiv{} |
|
|
425 eye (2, 2) |
|
|
426 @equiv{} |
|
|
427 eye (size ([1, 2; 3, 4]) |
|
|
428 @end group |
|
|
429 @end example |
|
|
430 |
|
|
431 For compatibility with @sc{Matlab}, calling @code{eye} with no arguments |
|
|
432 is equivalent to calling it with an argument of 1. |
|
|
433 @end deftypefn |
|
|
434 |
|
|
435 @deftypefn {Built-in Function} {} ones (@var{x}) |
|
|
436 @deftypefnx {Built-in Function} {} ones (@var{n}, @var{m}) |
|
2768
|
437 Return a matrix whose elements are all 1. The arguments are handled |
|
2670
|
438 the same as the arguments for @code{eye}. |
|
|
439 |
|
|
440 If you need to create a matrix whose values are all the same, you should |
|
|
441 use an expression like |
|
|
442 |
|
|
443 @example |
|
|
444 val_matrix = val * ones (n, m) |
|
|
445 @end example |
|
|
446 @end deftypefn |
|
|
447 |
|
|
448 @deftypefn {Built-in Function} {} zeros (@var{x}) |
|
|
449 @deftypefnx {Built-in Function} {} zeros (@var{n}, @var{m}) |
|
2768
|
450 Return a matrix whose elements are all 0. The arguments are handled |
|
2670
|
451 the same as the arguments for @code{eye}. |
|
|
452 @end deftypefn |
|
|
453 |
|
|
454 @deftypefn {Loadable Function} {} rand (@var{x}) |
|
|
455 @deftypefnx {Loadable Function} {} rand (@var{n}, @var{m}) |
|
|
456 @deftypefnx {Loadable Function} {} rand (@code{"seed"}, @var{x}) |
|
2768
|
457 Return a matrix with random elements uniformly distributed on the |
|
2670
|
458 interval (0, 1). The arguments are handled the same as the arguments |
|
|
459 for @code{eye}. In |
|
|
460 addition, you can set the seed for the random number generator using the |
|
|
461 form |
|
|
462 |
|
|
463 @example |
|
2689
|
464 rand ("seed", @var{x}) |
|
2670
|
465 @end example |
|
|
466 |
|
|
467 @noindent |
|
|
468 where @var{x} is a scalar value. If called as |
|
|
469 |
|
|
470 @example |
|
|
471 rand ("seed") |
|
|
472 @end example |
|
|
473 |
|
|
474 @noindent |
|
|
475 @code{rand} returns the current value of the seed. |
|
|
476 @end deftypefn |
|
|
477 |
|
|
478 @deftypefn {Loadable Function} {} randn (@var{x}) |
|
|
479 @deftypefnx {Loadable Function} {} randn (@var{n}, @var{m}) |
|
|
480 @deftypefnx {Loadable Function} {} randn (@code{"seed"}, @var{x}) |
|
2768
|
481 Return a matrix with normally distributed random elements. The |
|
2670
|
482 arguments are handled the same as the arguments for @code{eye}. In |
|
|
483 addition, you can set the seed for the random number generator using the |
|
|
484 form |
|
|
485 |
|
|
486 @example |
|
|
487 randn ("seed", @var{x}) |
|
|
488 @end example |
|
|
489 |
|
|
490 @noindent |
|
|
491 where @var{x} is a scalar value. If called as |
|
|
492 |
|
|
493 @example |
|
|
494 randn ("seed") |
|
|
495 @end example |
|
|
496 |
|
|
497 @noindent |
|
|
498 @code{randn} returns the current value of the seed. |
|
|
499 @end deftypefn |
|
|
500 |
|
|
501 The @code{rand} and @code{randn} functions use separate generators. |
|
|
502 This ensures that |
|
|
503 |
|
|
504 @example |
|
|
505 @group |
|
|
506 rand ("seed", 13); |
|
|
507 randn ("seed", 13); |
|
|
508 u = rand (100, 1); |
|
|
509 n = randn (100, 1); |
|
|
510 @end group |
|
|
511 @end example |
|
|
512 |
|
|
513 @noindent |
|
|
514 and |
|
|
515 |
|
|
516 @example |
|
|
517 @group |
|
|
518 rand ("seed", 13); |
|
|
519 randn ("seed", 13); |
|
|
520 u = zeros (100, 1); |
|
|
521 n = zeros (100, 1); |
|
|
522 for i = 1:100 |
|
|
523 u(i) = rand (); |
|
|
524 n(i) = randn (); |
|
|
525 end |
|
|
526 @end group |
|
|
527 @end example |
|
|
528 |
|
|
529 @noindent |
|
|
530 produce equivalent results. |
|
|
531 |
|
|
532 Normally, @code{rand} and @code{randn} obtain their initial |
|
|
533 seeds from the system clock, so that the sequence of random numbers is |
|
|
534 not the same each time you run Octave. If you really do need for to |
|
|
535 reproduce a sequence of numbers exactly, you can set the seed to a |
|
|
536 specific value. |
|
|
537 |
|
|
538 If it is invoked without arguments, @code{rand} and @code{randn} return a |
|
|
539 single element of a random sequence. |
|
|
540 |
|
2689
|
541 The @code{rand} and @code{randn} functions use Fortran code from |
|
|
542 @sc{Ranlib}, a library of fortran routines for random number generation, |
|
|
543 compiled by Barry W. Brown and James Lovato of the Department of |
|
|
544 Biomathematics at The University of Texas, M.D. Anderson Cancer Center, |
|
|
545 Houston, TX 77030. |
|
2670
|
546 |
|
|
547 @deftypefn {Built-in Function} {} diag (@var{v}, @var{k}) |
|
2768
|
548 Return a diagonal matrix with vector @var{v} on diagonal @var{k}. The |
|
2670
|
549 second argument is optional. If it is positive, the vector is placed on |
|
|
550 the @var{k}-th super-diagonal. If it is negative, it is placed on the |
|
|
551 @var{-k}-th sub-diagonal. The default value of @var{k} is 0, and the |
|
|
552 vector is placed on the main diagonal. For example, |
|
|
553 |
|
|
554 @example |
|
|
555 @group |
|
|
556 diag ([1, 2, 3], 1) |
|
|
557 @result{} 0 1 0 0 |
|
|
558 0 0 2 0 |
|
|
559 0 0 0 3 |
|
|
560 0 0 0 0 |
|
|
561 @end group |
|
|
562 @end example |
|
|
563 @end deftypefn |
|
|
564 |
|
|
565 @c XXX FIXME XXX -- is this really worth documenting? |
|
|
566 @c |
|
|
567 @c @defvr {Built-in Variable} ok_to_lose_imaginary_part |
|
|
568 @c If the value of @code{ok_to_lose_imaginary_part} is nonzero, implicit |
|
|
569 @c conversions of complex numbers to real numbers are allowed (for example, |
|
|
570 @c by fsolve). If the value is @code{"warn"}, the conversion is allowed, |
|
|
571 @c but a warning is printed. Otherwise, an error message is printed and |
|
|
572 @c control is returned to the top level. The default value is |
|
|
573 @c @code{"warn"}. |
|
|
574 @c |
|
|
575 @c XXX FIXME XXX -- this is here because it is used by @code{ones}, |
|
|
576 @c @code{zeros}, @code{rand}, etc. |
|
|
577 @c @end defvr |
|
|
578 |
|
|
579 The functions @code{linspace} and @code{logspace} make it very easy to |
|
|
580 create vectors with evenly or logarithmically spaced elements. |
|
|
581 @xref{Ranges}. |
|
|
582 |
|
|
583 @deftypefn {Function File} {} linspace (@var{base}, @var{limit}, @var{n}) |
|
2689
|
584 Return a row vector with @var{n} linearly spaced elements between |
|
|
585 @var{base} and @var{limit}. The number of elements, @var{n}, must be |
|
|
586 greater than 1. The @var{base} and @var{limit} are always included in |
|
|
587 the range. If @var{base} is greater than @var{limit}, the elements are |
|
|
588 stored in decreasing order. If the number of points is not specified, a |
|
|
589 value of 100 is used. |
|
2670
|
590 |
|
|
591 The @code{linspace} function always returns a row vector, regardless of |
|
|
592 the value of @code{prefer_column_vectors}. |
|
|
593 @end deftypefn |
|
|
594 |
|
|
595 @deftypefn {Function File} {} logspace (@var{base}, @var{limit}, @var{n}) |
|
|
596 Similar to @code{linspace} except that the values are logarithmically |
|
|
597 spaced from |
|
|
598 @iftex |
|
|
599 @tex |
|
|
600 $10^{base}$ to $10^{limit}$. |
|
|
601 @end tex |
|
|
602 @end iftex |
|
|
603 @ifinfo |
|
|
604 10^base to 10^limit. |
|
|
605 @end ifinfo |
|
|
606 |
|
|
607 If @var{limit} is equal to |
|
|
608 @iftex |
|
|
609 @tex |
|
|
610 $\pi$, |
|
|
611 @end tex |
|
|
612 @end iftex |
|
|
613 @ifinfo |
|
|
614 pi, |
|
|
615 @end ifinfo |
|
|
616 the points are between |
|
|
617 @iftex |
|
|
618 @tex |
|
|
619 $10^{base}$ and $\pi$, |
|
|
620 @end tex |
|
|
621 @end iftex |
|
|
622 @ifinfo |
|
|
623 10^base and pi, |
|
|
624 @end ifinfo |
|
|
625 @emph{not} |
|
|
626 @iftex |
|
|
627 @tex |
|
|
628 $10^{base}$ and $10^{\pi}$, |
|
|
629 @end tex |
|
|
630 @end iftex |
|
|
631 @ifinfo |
|
|
632 10^base and 10^pi, |
|
|
633 @end ifinfo |
|
|
634 in order to be compatible with the corresponding @sc{Matlab} function. |
|
|
635 @end deftypefn |
|
|
636 |
|
|
637 @defvr {Built-in Variable} treat_neg_dim_as_zero |
|
|
638 If the value of @code{treat_neg_dim_as_zero} is nonzero, expressions |
|
|
639 like |
|
|
640 |
|
|
641 @example |
|
|
642 eye (-1) |
|
|
643 @end example |
|
|
644 |
|
|
645 @noindent |
|
|
646 produce an empty matrix (i.e., row and column dimensions are zero). |
|
|
647 Otherwise, an error message is printed and control is returned to the |
|
|
648 top level. The default value is 0. |
|
|
649 @end defvr |
|
|
650 |
|
|
651 @node Famous Matrices, , Special Utility Matrices, Matrix Manipulation |
|
|
652 @section Famous Matrices |
|
|
653 |
|
|
654 The following functions return famous matrix forms. |
|
|
655 |
|
|
656 @deftypefn {Function File} {} hadamard (@var{k}) |
|
2689
|
657 Return the Hadamard matrix of order |
|
|
658 @iftex |
|
|
659 @tex |
|
|
660 $n = 2^k$. |
|
|
661 @end tex |
|
|
662 @end iftex |
|
|
663 @ifinfo |
|
|
664 n = 2^k. |
|
|
665 @end ifinfo |
|
2670
|
666 @end deftypefn |
|
|
667 |
|
|
668 @deftypefn {Function File} {} hankel (@var{c}, @var{r}) |
|
|
669 Return the Hankel matrix constructed given the first column @var{c}, and |
|
|
670 (optionally) the last row @var{r}. If the last element of @var{c} is |
|
|
671 not the same as the first element of @var{r}, the last element of |
|
|
672 @var{c} is used. If the second argument is omitted, the last row is |
|
|
673 taken to be the same as the first column. |
|
|
674 |
|
|
675 A Hankel matrix formed from an m-vector @var{c}, and an n-vector |
|
|
676 @var{r}, has the elements |
|
|
677 @iftex |
|
|
678 @tex |
|
|
679 $$ |
|
|
680 H (i, j) = \cases{c_{i+j-1},&$i+j-1\le m$;\cr r_{i+j-m},&otherwise.\cr} |
|
|
681 $$ |
|
|
682 @end tex |
|
|
683 @end iftex |
|
|
684 @ifinfo |
|
|
685 |
|
|
686 @example |
|
|
687 @group |
|
|
688 H (i, j) = c (i+j-1), i+j-1 <= m; |
|
|
689 H (i, j) = r (i+j-m), otherwise |
|
|
690 @end group |
|
|
691 @end example |
|
|
692 @end ifinfo |
|
|
693 @end deftypefn |
|
|
694 |
|
|
695 @deftypefn {Function File} {} hilb (@var{n}) |
|
|
696 Return the Hilbert matrix of order @var{n}. The |
|
|
697 @iftex |
|
|
698 @tex |
|
|
699 $i,\,j$ |
|
|
700 @end tex |
|
|
701 @end iftex |
|
|
702 @ifinfo |
|
|
703 i, j |
|
|
704 @end ifinfo |
|
|
705 element of a Hilbert matrix is defined as |
|
|
706 @iftex |
|
|
707 @tex |
|
|
708 $$ |
|
|
709 H (i, j) = {1 \over (i + j - 1)} |
|
|
710 $$ |
|
|
711 @end tex |
|
|
712 @end iftex |
|
|
713 @ifinfo |
|
|
714 |
|
|
715 @example |
|
|
716 H (i, j) = 1 / (i + j - 1) |
|
|
717 @end example |
|
|
718 @end ifinfo |
|
|
719 @end deftypefn |
|
|
720 |
|
|
721 @deftypefn {Function File} {} invhilb (@var{n}) |
|
|
722 Return the inverse of a Hilbert matrix of order @var{n}. This is exact. |
|
|
723 Compare with the numerical calculation of @code{inverse (hilb (n))}, |
|
|
724 which suffers from the ill-conditioning of the Hilbert matrix, and the |
|
|
725 finite precision of your computer's floating point arithmetic. |
|
|
726 @end deftypefn |
|
|
727 |
|
|
728 @deftypefn {Function File} {} toeplitz (@var{c}, @var{r}) |
|
|
729 Return the Toeplitz matrix constructed given the first column @var{c}, |
|
|
730 and (optionally) the first row @var{r}. If the first element of @var{c} |
|
|
731 is not the same as the first element of @var{r}, the first element of |
|
|
732 @var{c} is used. If the second argument is omitted, the first row is |
|
|
733 taken to be the same as the first column. |
|
|
734 |
|
|
735 A square Toeplitz matrix has the form |
|
|
736 @iftex |
|
|
737 @tex |
|
|
738 $$ |
|
|
739 \left[\matrix{c_0 & r_1 & r_2 & \ldots & r_n\cr |
|
|
740 c_1 & c_0 & r_1 & & c_{n-1}\cr |
|
|
741 c_2 & c_1 & c_0 & & c_{n-2}\cr |
|
|
742 \vdots & & & & \vdots\cr |
|
|
743 c_n & c_{n-1} & c_{n-2} & \ldots & c_0}\right]. |
|
|
744 $$ |
|
|
745 @end tex |
|
|
746 @end iftex |
|
|
747 @ifinfo |
|
|
748 |
|
|
749 @example |
|
|
750 @group |
|
|
751 c(0) r(1) r(2) ... r(n) |
|
|
752 c(1) c(0) r(1) r(n-1) |
|
|
753 c(2) c(1) c(0) r(n-2) |
|
|
754 . . |
|
|
755 . . |
|
|
756 . . |
|
|
757 |
|
|
758 c(n) c(n-1) c(n-2) ... c(0) |
|
|
759 @end group |
|
|
760 @end example |
|
|
761 @end ifinfo |
|
|
762 @end deftypefn |
|
|
763 |
|
|
764 @deftypefn {Function File} {} vander (@var{c}) |
|
|
765 Return the Vandermonde matrix whose next to last column is @var{c}. |
|
|
766 |
|
|
767 A Vandermonde matrix has the form |
|
|
768 @iftex |
|
|
769 @tex |
|
|
770 $$ |
|
|
771 \left[\matrix{c_0^n & \ldots & c_0^2 & c_0 & 1\cr |
|
|
772 c_1^n & \ldots & c_1^2 & c_1 & 1\cr |
|
|
773 \vdots & & \vdots & \vdots & \vdots\cr |
|
|
774 c_n^n & \ldots & c_n^2 & c_n & 1}\right]. |
|
|
775 $$ |
|
|
776 @end tex |
|
|
777 @end iftex |
|
|
778 @ifinfo |
|
|
779 |
|
|
780 @example |
|
|
781 @group |
|
|
782 c(0)^n ... c(0)^2 c(0) 1 |
|
|
783 c(1)^n ... c(1)^2 c(1) 1 |
|
|
784 . . . . |
|
|
785 . . . . |
|
|
786 . . . . |
|
|
787 |
|
|
788 c(n)^n ... c(n)^2 c(n) 1 |
|
|
789 @end group |
|
|
790 @end example |
|
|
791 @end ifinfo |
|
|
792 @end deftypefn |
