1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Matrices and Arrays in Oct-Files</title>
<meta name="description" content="GNU Octave: Matrices and Arrays in Oct-Files">
<meta name="keywords" content="GNU Octave: Matrices and Arrays in Oct-Files">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Oct_002dFiles.html#Oct_002dFiles" rel="up" title="Oct-Files">
<link href="Character-Strings-in-Oct_002dFiles.html#Character-Strings-in-Oct_002dFiles" rel="next" title="Character Strings in Oct-Files">
<link href="Getting-Started-with-Oct_002dFiles.html#Getting-Started-with-Oct_002dFiles" rel="prev" title="Getting Started with Oct-Files">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Matrices-and-Arrays-in-Oct_002dFiles"></a>
<div class="header">
<p>
Next: <a href="Character-Strings-in-Oct_002dFiles.html#Character-Strings-in-Oct_002dFiles" accesskey="n" rel="next">Character Strings in Oct-Files</a>, Previous: <a href="Getting-Started-with-Oct_002dFiles.html#Getting-Started-with-Oct_002dFiles" accesskey="p" rel="prev">Getting Started with Oct-Files</a>, Up: <a href="Oct_002dFiles.html#Oct_002dFiles" accesskey="u" rel="up">Oct-Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Matrices-and-Arrays-in-Oct_002dFiles-1"></a>
<h4 class="subsection">A.1.2 Matrices and Arrays in Oct-Files</h4>
<p>Octave supports a number of different array and matrix classes, the
majority of which are based on the Array class. The exception is the
sparse matrix types discussed separately below. There are three basic
matrix types
</p>
<dl compact="compact">
<dt><code>Matrix</code></dt>
<dd><p>A double precision matrix class defined in <samp>dMatrix.h</samp>,
</p>
</dd>
<dt><code>ComplexMatrix</code></dt>
<dd><p>A complex matrix class defined in <samp>CMatrix.h</samp>, and
</p>
</dd>
<dt><code>BoolMatrix</code></dt>
<dd><p>A boolean matrix class defined in <samp>boolMatrix.h</samp>.
</p></dd>
</dl>
<p>These are the basic two-dimensional matrix types of Octave. In
addition there are a number of multi-dimensional array types including
</p>
<dl compact="compact">
<dt><code>NDArray</code></dt>
<dd><p>A double precision array class defined in <samp>dNDArray.h</samp>
</p>
</dd>
<dt><code>ComplexNDarray</code></dt>
<dd><p>A complex array class defined in <samp>CNDArray.h</samp>
</p>
</dd>
<dt><code>boolNDArray</code></dt>
<dd><p>A boolean array class defined in <samp>boolNDArray.h</samp>
</p>
</dd>
<dt><code>int8NDArray</code></dt>
<dt><code>int16NDArray</code></dt>
<dt><code>int32NDArray</code></dt>
<dt><code>int64NDArray</code></dt>
<dd><p>8, 16, 32, and 64-bit signed array classes defined in
<samp>int8NDArray.h</samp>, <samp>int16NDArray.h</samp>, etc.
</p>
</dd>
<dt><code>uint8NDArray</code></dt>
<dt><code>uint16NDArray</code></dt>
<dt><code>uint32NDArray</code></dt>
<dt><code>uint64NDArray</code></dt>
<dd><p>8, 16, 32, and 64-bit unsigned array classes defined in
<samp>uint8NDArray.h</samp>, <samp>uint16NDArray.h</samp>, etc.
</p></dd>
</dl>
<p>There are several basic ways of constructing matrices or
multi-dimensional arrays. Using the class <code>Matrix</code> as an example
one can
</p>
<ul>
<li> Create an empty matrix or array with the empty constructor. For example:
<div class="example">
<pre class="example">Matrix a;
</pre></div>
<p>This can be used for all matrix and array types.
</p>
</li><li> Define the dimensions of the matrix or array with a dim_vector which has
the same characteristics as the vector returned from <code>size</code>. For example:
<div class="example">
<pre class="example">dim_vector dv (2);
dv(0) = 2; dv(1) = 3; // 2 rows, 3 columns
Matrix a (dv);
</pre></div>
<p>This can be used on all matrix and array types.
</p>
</li><li> Define the number of rows and columns in the matrix. For example:
<div class="example">
<pre class="example">Matrix a (2, 2)
</pre></div>
<p>However, this constructor can only be used with matrix types.
</p></li></ul>
<p>These types all share a number of basic methods and operators. Many bear
a resemblance to functions that exist in the interpreter. A selection of
useful methods include
</p>
<dl>
<dt><a name="index-operator"></a>Method: <em>T&</em> <strong>operator</strong> <em>() (octave_idx_type)</em></dt>
<dt><a name="index-elem"></a>Method: <em>T&</em> <strong>elem</strong> <em>(octave_idx_type)</em></dt>
<dd><p>The <code>()</code> operator or <code>elem</code> method allow the values of the
matrix or array to be read or set. These can take a single argument,
which is of type <code>octave_idx_type</code>, that is the index into the matrix or
array. Additionally, the matrix type allows two argument versions of the
<code>()</code> operator and elem method, giving the row and column index of the
value to obtain or set.
</p></dd></dl>
<p>Note that these functions do significant error checking and so in some
circumstances the user might prefer to access the data of the array or
matrix directly through the fortran_vec method discussed below.
</p>
<dl>
<dt><a name="index-octave_005fidx_005ftype"></a>Method: <em></em> <strong>octave_idx_type</strong> <em>numel (void) const</em></dt>
<dd><p>The total number of elements in the matrix or array.
</p></dd></dl>
<dl>
<dt><a name="index-byte_005fsize"></a>Method: <em>size_t</em> <strong>byte_size</strong> <em>(void) const</em></dt>
<dd><p>The number of bytes used to store the matrix or array.
</p></dd></dl>
<dl>
<dt><a name="index-dims"></a>Method: <em>dim_vector</em> <strong>dims</strong> <em>(void) const</em></dt>
<dd><p>The dimensions of the matrix or array in value of type dim_vector.
</p></dd></dl>
<dl>
<dt><a name="index-ndims-1"></a>Method: <em>int</em> <strong>ndims</strong> <em>(void) const</em></dt>
<dd><p>The number of dimensions of the matrix or array. Matrices are 2-D,
but arrays can be N-dimensional.
</p></dd></dl>
<dl>
<dt><a name="index-resize-3"></a>Method: <em>void</em> <strong>resize</strong> <em>(const dim_vector&)</em></dt>
<dd><p>A method taking either an argument of type <code>dim_vector</code>, or in the
case of a matrix two arguments of type <code>octave_idx_type</code> defining
the number of rows and columns in the matrix.
</p></dd></dl>
<dl>
<dt><a name="index-fortran_005fvec"></a>Method: <em>T*</em> <strong>fortran_vec</strong> <em>(void)</em></dt>
<dd><p>This method returns a pointer to the underlying data of the matrix or
array so that it can be manipulated directly, either within Octave or by
an external library.
</p></dd></dl>
<p>Operators such an <code>+</code>, <code>-</code>, or <code>*</code> can be used on the
majority of the matrix and array types. In addition there are a number of
methods that are of interest only for matrices such as <code>transpose</code>,
<code>hermitian</code>, <code>solve</code>, etc.
</p>
<p>The typical way to extract a matrix or array from the input arguments of
<code><span class="nolinebreak">DEFUN_DLD</span></code><!-- /@w --> function is as follows
</p>
<div class="example">
<pre class="verbatim">#include <octave/oct.h>
DEFUN_DLD (addtwomatrices, args, , "Add A to B")
{
int nargin = args.length ();
if (nargin != 2)
print_usage ();
else
{
NDArray A = args(0).array_value ();
NDArray B = args(1).array_value ();
if (! error_state)
return octave_value (A + B);
}
return octave_value_list ();
}
</pre><pre class="example">
</pre></div>
<p>To avoid segmentation faults causing Octave to abort this function
explicitly checks that there are sufficient arguments available before
accessing these arguments. It then obtains two multi-dimensional arrays
of type <code>NDArray</code> and adds these together. Note that the array_value
method is called without using the <code>is_matrix_type</code> type, and instead the
error_state is checked before returning <code>A + B</code>. The reason to
prefer this is that the arguments might be a type that is not an
<code>NDArray</code>, but it would make sense to convert it to one. The
<code>array_value</code> method allows this conversion to be performed
transparently if possible, and sets <code>error_state</code> if it is not.
</p>
<p><code>A + B</code>, operating on two <code>NDArray</code>’s returns an
<code>NDArray</code>, which is cast to an <code>octave_value</code> on the return
from the function. An example of the use of this demonstration function is
</p>
<div class="example">
<pre class="example">addtwomatrices (ones (2, 2), eye (2, 2))
⇒ 2 1
1 2
</pre></div>
<p>A list of the basic <code>Matrix</code> and <code>Array</code> types, the methods to
extract these from an <code>octave_value</code>, and the associated header file is
listed below.
</p>
<table>
<thead><tr><th width="30%">Type</th><th width="40%">Function</th><th width="30%">Source Code</th></tr></thead>
<tr><td width="30%"><code>RowVector</code></td><td width="40%"><code>row_vector_value</code></td><td width="30%"><samp>dRowVector.h</samp></td></tr>
<tr><td width="30%"><code>ComplexRowVector</code></td><td width="40%"><code>complex_row_vector_value</code></td><td width="30%"><samp>CRowVector.h</samp></td></tr>
<tr><td width="30%"><code>ColumnVector</code></td><td width="40%"><code>column_vector_value</code></td><td width="30%"><samp>dColVector.h</samp></td></tr>
<tr><td width="30%"><code>ComplexColumnVector</code></td><td width="40%"><code>complex_column_vector_value</code></td><td width="30%"><samp>CColVector.h</samp></td></tr>
<tr><td width="30%"><code>Matrix</code></td><td width="40%"><code>matrix_value</code></td><td width="30%"><samp>dMatrix.h</samp></td></tr>
<tr><td width="30%"><code>ComplexMatrix</code></td><td width="40%"><code>complex_matrix_value</code></td><td width="30%"><samp>CMatrix.h</samp></td></tr>
<tr><td width="30%"><code>boolMatrix</code></td><td width="40%"><code>bool_matrix_value</code></td><td width="30%"><samp>boolMatrix.h</samp></td></tr>
<tr><td width="30%"><code>charMatrix</code></td><td width="40%"><code>char_matrix_value</code></td><td width="30%"><samp>chMatrix.h</samp></td></tr>
<tr><td width="30%"><code>NDArray</code></td><td width="40%"><code>array_value</code></td><td width="30%"><samp>dNDArray.h</samp></td></tr>
<tr><td width="30%"><code>ComplexNDArray</code></td><td width="40%"><code>complex_array_value</code></td><td width="30%"><samp>CNDArray.h</samp></td></tr>
<tr><td width="30%"><code>boolNDArray</code></td><td width="40%"><code>bool_array_value</code></td><td width="30%"><samp>boolNDArray.h</samp></td></tr>
<tr><td width="30%"><code>charNDArray</code></td><td width="40%"><code>char_array_value</code></td><td width="30%"><samp>charNDArray.h</samp></td></tr>
<tr><td width="30%"><code>int8NDArray</code></td><td width="40%"><code>int8_array_value</code></td><td width="30%"><samp>int8NDArray.h</samp></td></tr>
<tr><td width="30%"><code>int16NDArray</code></td><td width="40%"><code>int16_array_value</code></td><td width="30%"><samp>int16NDArray.h</samp></td></tr>
<tr><td width="30%"><code>int32NDArray</code></td><td width="40%"><code>int32_array_value</code></td><td width="30%"><samp>int32NDArray.h</samp></td></tr>
<tr><td width="30%"><code>int64NDArray</code></td><td width="40%"><code>int64_array_value</code></td><td width="30%"><samp>int64NDArray.h</samp></td></tr>
<tr><td width="30%"><code>uint8NDArray</code></td><td width="40%"><code>uint8_array_value</code></td><td width="30%"><samp>uint8NDArray.h</samp></td></tr>
<tr><td width="30%"><code>uint16NDArray</code></td><td width="40%"><code>uint16_array_value</code></td><td width="30%"><samp>uint16NDArray.h</samp></td></tr>
<tr><td width="30%"><code>uint32NDArray</code></td><td width="40%"><code>uint32_array_value</code></td><td width="30%"><samp>uint32NDArray.h</samp></td></tr>
<tr><td width="30%"><code>uint64NDArray</code></td><td width="40%"><code>uint64_array_value</code></td><td width="30%"><samp>uint64NDArray.h</samp></td></tr>
</table>
<hr>
<div class="header">
<p>
Next: <a href="Character-Strings-in-Oct_002dFiles.html#Character-Strings-in-Oct_002dFiles" accesskey="n" rel="next">Character Strings in Oct-Files</a>, Previous: <a href="Getting-Started-with-Oct_002dFiles.html#Getting-Started-with-Oct_002dFiles" accesskey="p" rel="prev">Getting Started with Oct-Files</a>, Up: <a href="Oct_002dFiles.html#Oct_002dFiles" accesskey="u" rel="up">Oct-Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
