Mercurial > octave-nkf
annotate doc/interpreter/dynamic.txi @ 10828:322f43e0e170
Grammarcheck .txi documentation files.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Wed, 28 Jul 2010 12:45:04 -0700 |
parents | 3140cb7a05a1 |
children | a4f482e66b65 |
rev | line source |
---|---|
8920 | 1 @c Copyright (C) 2007, 2008, 2009 John W. Eaton and David Bateman |
7018 | 2 @c Copyright (C) 2007 Paul Thomas and Christoph Spiel |
3 @c | |
4 @c This file is part of Octave. | |
5 @c | |
6 @c Octave is free software; you can redistribute it and/or modify it | |
7 @c under the terms of the GNU General Public License as published by the | |
8 @c Free Software Foundation; either version 3 of the License, or (at | |
9 @c your option) any later version. | |
10 @c | |
11 @c Octave is distributed in the hope that it will be useful, but WITHOUT | |
12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
14 @c for more details. | |
15 @c | |
16 @c You should have received a copy of the GNU General Public License | |
17 @c along with Octave; see the file COPYING. If not, see | |
18 @c <http://www.gnu.org/licenses/>. | |
6578 | 19 |
6569 | 20 @node Dynamically Linked Functions |
21 @appendix Dynamically Linked Functions | |
22 @cindex dynamic-linking | |
23 | |
24 Octave has the possibility of including compiled code as dynamically | |
25 linked extensions and then using these extensions as if they were part | |
8828 | 26 of Octave itself. Octave can call C++ code |
6569 | 27 through its native oct-file interface or C code through its mex |
6571 | 28 interface. It can also indirectly call functions written in any other |
29 language through a simple wrapper. The reasons to write code in a | |
6569 | 30 compiled language might be either to link to an existing piece of code |
31 and allow it to be used within Octave, or to allow improved performance | |
32 for key pieces of code. | |
33 | |
34 Before going further, you should first determine if you really need to | |
6571 | 35 use dynamically linked functions at all. Before proceeding with writing |
6569 | 36 any dynamically linked function to improve performance you should |
37 address ask yourself | |
38 | |
39 @itemize @bullet | |
40 @item | |
6939 | 41 Can I get the same functionality using the Octave scripting language only? |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
42 |
6569 | 43 @item |
6572 | 44 Is it thoroughly optimized Octave code? Vectorization of Octave code, |
6569 | 45 doesn't just make it concise, it generally significantly improves its |
6571 | 46 performance. Above all, if loops must be used, make sure that the |
6569 | 47 allocation of space for variables takes place outside the loops using an |
8828 | 48 assignment to a matrix of the right size, or zeros. |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
49 |
6569 | 50 @item |
51 Does it make as much use as possible of existing built-in library | |
6572 | 52 routines? These are highly optimized and many do not carry the overhead |
6569 | 53 of being interpreted. |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
54 |
6569 | 55 @item |
56 Does writing a dynamically linked function represent useful investment | |
57 of your time, relative to staying in Octave? | |
58 @end itemize | |
59 | |
8475 | 60 Also, as oct- and mex-files are dynamically linked to Octave, they |
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8097
diff
changeset
|
61 introduce the possibility of Octave crashing due to errors in |
7001 | 62 the user code. For example a segmentation violation in the user's code |
6569 | 63 will cause Octave to abort. |
64 | |
65 @menu | |
6572 | 66 * Oct-Files:: |
67 * Mex-Files:: | |
68 * Standalone Programs:: | |
6569 | 69 @end menu |
70 | |
71 @node Oct-Files | |
72 @section Oct-Files | |
73 @cindex oct-files | |
74 @cindex mkoctfile | |
75 @cindex oct | |
76 | |
77 @menu | |
6572 | 78 * Getting Started with Oct-Files:: |
79 * Matrices and Arrays in Oct-Files:: | |
80 * Character Strings in Oct-Files:: | |
81 * Cell Arrays in Oct-Files:: | |
82 * Structures in Oct-Files:: | |
83 * Sparse Matrices in Oct-Files:: | |
84 * Accessing Global Variables in Oct-Files:: | |
85 * Calling Octave Functions from Oct-Files:: | |
86 * Calling External Code from Oct-Files:: | |
87 * Allocating Local Memory in Oct-Files:: | |
88 * Input Parameter Checking in Oct-Files:: | |
89 * Exception and Error Handling in Oct-Files:: | |
90 * Documentation and Test of Oct-Files:: | |
6593 | 91 @c * Application Programming Interface for Oct-Files:: |
6569 | 92 @end menu |
93 | |
94 @node Getting Started with Oct-Files | |
95 @subsection Getting Started with Oct-Files | |
96 | |
97 The basic command to build oct-files is @code{mkoctfile} and it can be | |
98 call from within octave or from the command line. | |
99 | |
100 @DOCSTRING(mkoctfile) | |
101 | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
102 Consider the short example: |
6569 | 103 |
9906 | 104 @example |
105 @group | |
106 @EXAMPLEFILE(helloworld.cc) | |
107 @end group | |
108 @end example | |
6569 | 109 |
110 This example although short introduces the basics of writing a C++ | |
6571 | 111 function that can be dynamically linked to Octave. The easiest way to |
6569 | 112 make available most of the definitions that might be necessary for an |
113 oct-file in Octave is to use the @code{#include <octave/oct.h>} | |
6571 | 114 header. |
6569 | 115 |
116 The macro that defines the entry point into the dynamically loaded | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
117 function is @w{@code{DEFUN_DLD}}. This macro takes four arguments, these being |
6569 | 118 |
119 @enumerate 1 | |
6571 | 120 @item The function name as it will be seen in Octave, |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
121 |
6572 | 122 @item The list of arguments to the function of type @code{octave_value_list}, |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
123 |
6569 | 124 @item The number of output arguments, which can and often is omitted if |
125 not used, and | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
126 |
6569 | 127 @item The string that will be seen as the help text of the function. |
128 @end enumerate | |
129 | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
130 The return type of functions defined with @w{@code{DEFUN_DLD}} is always |
6572 | 131 @code{octave_value_list}. |
6569 | 132 |
133 There are a couple of important considerations in the choice of function | |
6571 | 134 name. Firstly, it must be a valid Octave function name and so must be a |
6569 | 135 sequence of letters, digits and underscores, not starting with a |
6571 | 136 digit. Secondly, as Octave uses the function name to define the filename |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
137 it attempts to find the function in, the function name in the |
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
138 @w{@code{DEFUN_DLD}} macro must match the filename of the oct-file. Therefore, |
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
139 the above function should be in a file @file{helloworld.cc}, and it should be |
6572 | 140 compiled to an oct-file using the command |
6569 | 141 |
142 @example | |
143 mkoctfile helloworld.cc | |
144 @end example | |
145 | |
8828 | 146 This will create a file called @file{helloworld.oct}, that is the compiled |
6571 | 147 version of the function. It should be noted that it is perfectly |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
148 acceptable to have more than one @w{@code{DEFUN_DLD}} function in a source |
6571 | 149 file. However, there must either be a symbolic link to the oct-file for |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
150 each of the functions defined in the source code with the @w{@code{DEFUN_DLD}} |
6569 | 151 macro or the autoload (@ref{Function Files}) function should be used. |
152 | |
153 The rest of this function then shows how to find the number of input | |
154 arguments, how to print through the octave pager, and return from the | |
6571 | 155 function. After compiling this function as above, an example of its use |
6569 | 156 is |
157 | |
158 @example | |
159 @group | |
6572 | 160 helloworld (1, 2, 3) |
161 @print{} Hello World has 3 input arguments and 0 output arguments. | |
6569 | 162 @end group |
163 @end example | |
164 | |
165 @node Matrices and Arrays in Oct-Files | |
166 @subsection Matrices and Arrays in Oct-Files | |
167 | |
168 Octave supports a number of different array and matrix classes, the | |
6571 | 169 majority of which are based on the Array class. The exception is the |
170 sparse matrix types discussed separately below. There are three basic | |
171 matrix types | |
6569 | 172 |
6572 | 173 @table @code |
6569 | 174 @item Matrix |
175 A double precision matrix class defined in dMatrix.h, | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
176 |
6569 | 177 @item ComplexMatrix |
178 A complex matrix class defined in CMatrix.h, and | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
179 |
6569 | 180 @item BoolMatrix |
181 A boolean matrix class defined in boolMatrix.h. | |
182 @end table | |
183 | |
6571 | 184 These are the basic two-dimensional matrix types of octave. In |
6569 | 185 additional there are a number of multi-dimensional array types, these |
186 being | |
187 | |
6572 | 188 @table @code |
6569 | 189 @item NDArray |
6572 | 190 A double precision array class defined in @file{dNDArray.h} |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
191 |
6569 | 192 @item ComplexNDarray |
6572 | 193 A complex array class defined in @file{CNDArray.h} |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
194 |
6569 | 195 @item boolNDArray |
6572 | 196 A boolean array class defined in @file{boolNDArray.h} |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
197 |
6572 | 198 @item int8NDArray |
199 @itemx int16NDArray | |
200 @itemx int32NDArray | |
201 @itemx int64NDArray | |
202 8, 16, 32 and 64-bit signed array classes defined in | |
203 @file{int8NDArray.h}, @file{int16NDArray.h}, etc. | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
204 |
6572 | 205 @item uint8NDArray |
206 @itemx uint16NDArray | |
207 @itemx uint32NDArray | |
208 @itemx uint64NDArray | |
209 8, 16, 32 and 64-bit unsigned array classes defined in | |
210 @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc. | |
6569 | 211 @end table |
212 | |
213 There are several basic means of constructing matrices of | |
6572 | 214 multi-dimensional arrays. Considering the @code{Matrix} type as an |
215 example | |
6569 | 216 |
217 @itemize @bullet | |
6571 | 218 @item |
219 We can create an empty matrix or array with the empty constructor. For | |
6569 | 220 example |
221 | |
222 @example | |
223 Matrix a; | |
224 @end example | |
225 | |
226 This can be used on all matrix and array types | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
227 |
6571 | 228 @item |
229 Define the dimensions of the matrix or array with a dim_vector. For | |
6569 | 230 example |
231 | |
232 @example | |
233 @group | |
6572 | 234 dim_vector dv (2); |
6569 | 235 dv(0) = 2; dv(1) = 2; |
6572 | 236 Matrix a (dv); |
6569 | 237 @end group |
238 @end example | |
239 | |
240 This can be used on all matrix and array types | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
241 |
6569 | 242 @item |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
243 Define the number of rows and columns in the matrix. For example: |
6569 | 244 |
245 @example | |
6572 | 246 Matrix a (2, 2) |
6569 | 247 @end example |
248 | |
249 However, this constructor can only be used with the matrix types. | |
250 @end itemize | |
251 | |
252 These types all share a number of basic methods and operators, a | |
253 selection of which include | |
254 | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
255 @deftypefn Method T& {operator ()} (octave_idx_type) |
6572 | 256 @deftypefnx Method T& elem (octave_idx_type) |
257 The @code{()} operator or @code{elem} method allow the values of the | |
258 matrix or array to be read or set. These can take a single argument, | |
259 which is of type @code{octave_idx_type}, that is the index into the matrix or | |
6571 | 260 array. Additionally, the matrix type allows two argument versions of the |
6572 | 261 @code{()} operator and elem method, giving the row and column index of the |
6569 | 262 value to obtain or set. |
6572 | 263 @end deftypefn |
6569 | 264 |
7001 | 265 Note that these functions do significant error checking and so in some |
266 circumstances the user might prefer to access the data of the array or | |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
267 matrix directly through the @nospell{fortran_vec} method discussed below. |
6572 | 268 |
269 @deftypefn Method octave_idx_type nelem (void) const | |
6569 | 270 The total number of elements in the matrix or array. |
6572 | 271 @end deftypefn |
272 | |
273 @deftypefn Method size_t byte_size (void) const | |
6569 | 274 The number of bytes used to store the matrix or array. |
6572 | 275 @end deftypefn |
276 | |
277 @deftypefn Method dim_vector dims (void) const | |
6569 | 278 The dimensions of the matrix or array in value of type dim_vector. |
6572 | 279 @end deftypefn |
280 | |
281 @deftypefn Method void resize (const dim_vector&) | |
282 A method taking either an argument of type @code{dim_vector}, or in the | |
283 case of a matrix two arguments of type @code{octave_idx_type} defining | |
284 the number of rows and columns in the matrix. | |
285 @end deftypefn | |
286 | |
287 @deftypefn Method T* fortran_vec (void) | |
6569 | 288 This method returns a pointer to the underlying data of the matrix or a |
289 array so that it can be manipulated directly, either within Octave or by | |
290 an external library. | |
6572 | 291 @end deftypefn |
6569 | 292 |
6572 | 293 Operators such an @code{+}, @code{-}, or @code{*} can be used on the |
294 majority of the above types. In addition there are a number of methods | |
295 that are of interest only for matrices such as @code{transpose}, | |
296 @code{hermitian}, @code{solve}, etc. | |
6569 | 297 |
298 The typical way to extract a matrix or array from the input arguments of | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
299 @w{@code{DEFUN_DLD}} function is as follows |
6569 | 300 |
9906 | 301 @example |
302 @group | |
303 @EXAMPLEFILE(addtwomatrices.cc) | |
304 @end group | |
305 @end example | |
6569 | 306 |
307 To avoid segmentation faults causing Octave to abort, this function | |
308 explicitly checks that there are sufficient arguments available before | |
6571 | 309 accessing these arguments. It then obtains two multi-dimensional arrays |
6572 | 310 of type @code{NDArray} and adds these together. Note that the array_value |
311 method is called without using the @code{is_matrix_type} type, and instead the | |
6571 | 312 error_state is checked before returning @code{A + B}. The reason to |
6569 | 313 prefer this is that the arguments might be a type that is not an |
6572 | 314 @code{NDArray}, but it would make sense to convert it to one. The |
315 @code{array_value} method allows this conversion to be performed | |
316 transparently if possible, and sets @code{error_state} if it is not. | |
6569 | 317 |
6572 | 318 @code{A + B}, operating on two @code{NDArray}'s returns an |
319 @code{NDArray}, which is cast to an @code{octave_value} on the return | |
320 from the function. An example of the use of this demonstration function | |
321 is | |
6569 | 322 |
323 @example | |
324 @group | |
6572 | 325 addtwomatrices (ones (2, 2), ones (2, 2)) |
6569 | 326 @result{} 2 2 |
327 2 2 | |
328 @end group | |
329 @end example | |
330 | |
6572 | 331 A list of the basic @code{Matrix} and @code{Array} types, the methods to |
332 extract these from an @code{octave_value} and the associated header is | |
333 listed below. | |
6569 | 334 |
335 @multitable @columnfractions .3 .4 .3 | |
6572 | 336 @item @code{RowVector} @tab @code{row_vector_value} @tab @file{dRowVector.h} |
337 @item @code{ComplexRowVector} @tab @code{complex_row_vector_value} @tab @file{CRowVector.h} | |
338 @item @code{ColumnVector} @tab @code{column_vector_value} @tab @file{dColVector.h} | |
339 @item @code{ComplexColumnVector} @tab @code{complex_column_vector_value} @tab @file{CColVector.h} | |
340 @item @code{Matrix} @tab @code{matrix_value} @tab @file{dMatrix.h} | |
341 @item @code{ComplexMatrix} @tab @code{complex_matrix_value} @tab @file{CMatrix.h} | |
342 @item @code{boolMatrix} @tab @code{bool_matrix_value} @tab @file{boolMatrix.h} | |
343 @item @code{charMatrix} @tab @code{char_matrix_value} @tab @file{chMatrix.h} | |
344 @item @code{NDArray} @tab @code{array_value} @tab @file{dNDArray.h} | |
345 @item @code{ComplexNDArray} @tab @code{complex_array_value} @tab @file{CNDArray.h} | |
346 @item @code{boolNDArray} @tab @code{bool_array_value} @tab @file{boolNDArray.h} | |
347 @item @code{charNDArray} @tab @code{char_array_value} @tab @file{charNDArray.h} | |
348 @item @code{int8NDArray} @tab @code{int8_array_value} @tab @file{int8NDArray.h} | |
349 @item @code{int16NDArray} @tab @code{int16_array_value} @tab @file{int16NDArray.h} | |
350 @item @code{int32NDArray} @tab @code{int32_array_value} @tab @file{int32NDArray.h} | |
351 @item @code{int64NDArray} @tab @code{int64_array_value} @tab @file{int64NDArray.h} | |
352 @item @code{uint8NDArray} @tab @code{uint8_array_value} @tab @file{uint8NDArray.h} | |
353 @item @code{uint16NDArray} @tab @code{uint16_array_value} @tab @file{uint16NDArray.h} | |
354 @item @code{uint32NDArray} @tab @code{uint32_array_value} @tab @file{uint32NDArray.h} | |
355 @item @code{uint64NDArray} @tab @code{uint64_array_value} @tab @file{uint64NDArray.h} | |
6569 | 356 @end multitable |
357 | |
6572 | 358 @node Character Strings in Oct-Files |
359 @subsection Character Strings in Oct-Files | |
360 | |
361 In Octave a character string is just a special @code{Array} class. | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
362 Consider the example: |
6572 | 363 |
9906 | 364 @example |
365 @EXAMPLEFILE(stringdemo.cc) | |
366 @end example | |
6572 | 367 |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
368 An example of the use of this function is |
6572 | 369 |
370 @example | |
371 @group | |
372 s0 = ["First String"; "Second String"]; | |
373 [s1,s2] = stringdemo (s0) | |
374 @result{} s1 = Second String | |
375 First String | |
376 | |
377 @result{} s2 = First String | |
378 Second String | |
379 | |
380 typeinfo (s2) | |
381 @result{} sq_string | |
382 typeinfo (s1) | |
383 @result{} string | |
384 @end group | |
385 @end example | |
386 | |
387 One additional complication of strings in Octave is the difference | |
388 between single quoted and double quoted strings. To find out if an | |
389 @code{octave_value} contains a single or double quoted string an example is | |
390 | |
391 @example | |
392 @group | |
393 if (args(0).is_sq_string ()) | |
7081 | 394 octave_stdout << |
395 "First argument is a singularly quoted string\n"; | |
6572 | 396 else if (args(0).is_dq_string ()) |
7081 | 397 octave_stdout << |
398 "First argument is a doubly quoted string\n"; | |
6572 | 399 @end group |
400 @end example | |
401 | |
402 Note however, that both types of strings are represented by the | |
403 @code{charNDArray} type, and so when assigning to an | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
404 @code{octave_value}, the type of string should be specified. For example: |
6572 | 405 |
406 @example | |
407 @group | |
408 octave_value_list retval; | |
409 charNDArray c; | |
410 @dots{} | |
6577 | 411 // Create single quoted string |
412 retval(1) = octave_value (ch, true, '\''); | |
413 | |
414 // Create a double quoted string | |
415 retval(0) = octave_value (ch, true); | |
6572 | 416 @end group |
417 @end example | |
418 | |
419 @node Cell Arrays in Oct-Files | |
420 @subsection Cell Arrays in Oct-Files | |
421 | |
7001 | 422 Octave's cell type is equally accessible within oct-files. A cell |
6572 | 423 array is just an array of @code{octave_value}s, and so each element of the cell |
424 array can then be treated just like any other @code{octave_value}. A simple | |
425 example is | |
426 | |
9906 | 427 @example |
428 @group | |
429 @EXAMPLEFILE(celldemo.cc) | |
430 @end group | |
431 @end example | |
6572 | 432 |
433 Note that cell arrays are used less often in standard oct-files and so | |
434 the @file{Cell.h} header file must be explicitly included. The rest of this | |
435 example extracts the @code{octave_value}s one by one from the cell array and | |
436 returns be as individual return arguments. For example consider | |
437 | |
438 @example | |
439 @group | |
440 [b1, b2, b3] = celldemo (@{1, [1, 2], "test"@}) | |
441 @result{} | |
442 b1 = 1 | |
443 b2 = | |
444 | |
445 1 2 | |
446 | |
447 b3 = test | |
448 @end group | |
449 @end example | |
450 | |
451 @node Structures in Oct-Files | |
452 @subsection Structures in Oct-Files | |
453 | |
454 A structure in Octave is map between a number of fields represented and | |
455 their values. The Standard Template Library @code{map} class is used, | |
456 with the pair consisting of a @code{std::string} and an octave | |
457 @code{Cell} variable. | |
458 | |
459 A simple example demonstrating the use of structures within oct-files is | |
460 | |
9906 | 461 @example |
462 @EXAMPLEFILE(structdemo.cc) | |
463 @end example | |
6572 | 464 |
465 An example of its use is | |
466 | |
467 @example | |
468 @group | |
469 x.a = 1; x.b = "test"; x.c = [1, 2]; | |
470 structdemo (x, "b") | |
471 @result{} selected = test | |
472 @end group | |
473 @end example | |
474 | |
7001 | 475 The commented code above demonstrates how to iterate over all of the |
6572 | 476 fields of the structure, where as the following code demonstrates finding |
477 a particular field in a more concise manner. | |
478 | |
479 As can be seen the @code{contents} method of the @code{Octave_map} class | |
480 returns a @code{Cell} which allows structure arrays to be represented. | |
481 Therefore, to obtain the underlying @code{octave_value} we write | |
482 | |
483 @example | |
484 octave_value tmp = arg0.contents (p1) (0); | |
485 @end example | |
486 | |
6593 | 487 where the trailing (0) is the () operator on the @code{Cell} object. We |
488 can equally iterate of the elements of the Cell array to address the | |
489 elements of the structure array. | |
6572 | 490 |
491 @node Sparse Matrices in Oct-Files | |
492 @subsection Sparse Matrices in Oct-Files | |
6569 | 493 |
494 There are three classes of sparse objects that are of interest to the | |
495 user. | |
496 | |
6572 | 497 @table @code |
6569 | 498 @item SparseMatrix |
499 A double precision sparse matrix class | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
500 |
6569 | 501 @item SparseComplexMatrix |
502 A complex sparse matrix class | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
503 |
6569 | 504 @item SparseBoolMatrix |
505 A boolean sparse matrix class | |
506 @end table | |
507 | |
508 All of these classes inherit from the @code{Sparse<T>} template class, | |
6571 | 509 and so all have similar capabilities and usage. The @code{Sparse<T>} |
6569 | 510 class was based on Octave @code{Array<T>} class, and so users familiar |
6572 | 511 with Octave's @code{Array} classes will be comfortable with the use of |
6569 | 512 the sparse classes. |
513 | |
514 The sparse classes will not be entirely described in this section, due | |
6572 | 515 to their similarity with the existing @code{Array} classes. However, |
516 there are a few differences due the different nature of sparse objects, | |
517 and these will be described. Firstly, although it is fundamentally | |
518 possible to have N-dimensional sparse objects, the Octave sparse classes do | |
6571 | 519 not allow them at this time. So all operations of the sparse classes |
6569 | 520 must be 2-dimensional. This means that in fact @code{SparseMatrix} is |
521 similar to Octave's @code{Matrix} class rather than its | |
522 @code{NDArray} class. | |
523 | |
524 @menu | |
6572 | 525 * Array and Sparse Differences:: |
526 * Creating Sparse Matrices in Oct-Files:: | |
527 * Using Sparse Matrices in Oct-Files:: | |
6569 | 528 @end menu |
529 | |
6572 | 530 @node Array and Sparse Differences |
6569 | 531 @subsubsection The Differences between the Array and Sparse Classes |
532 | |
533 The number of elements in a sparse matrix is considered to be the number | |
6571 | 534 of non-zero elements rather than the product of the dimensions. Therefore |
6569 | 535 |
536 @example | |
6577 | 537 @group |
538 SparseMatrix sm; | |
539 @dots{} | |
540 int nel = sm.nelem (); | |
541 @end group | |
6569 | 542 @end example |
543 | |
6571 | 544 returns the number of non-zero elements. If the user really requires the |
6569 | 545 number of elements in the matrix, including the non-zero elements, they |
6571 | 546 should use @code{numel} rather than @code{nelem}. Note that for very |
7001 | 547 large matrices, where the product of the two dimensions is larger than |
548 the representation of an unsigned int, then @code{numel} can overflow. | |
6569 | 549 An example is @code{speye(1e6)} which will create a matrix with a million |
6571 | 550 rows and columns, but only a million non-zero elements. Therefore the |
6569 | 551 number of rows by the number of columns in this case is more than two |
552 hundred times the maximum value that can be represented by an unsigned int. | |
553 The use of @code{numel} should therefore be avoided useless it is known | |
554 it won't overflow. | |
555 | |
556 Extreme care must be take with the elem method and the "()" operator, | |
6571 | 557 which perform basically the same function. The reason is that if a |
6569 | 558 sparse object is non-const, then Octave will assume that a |
6571 | 559 request for a zero element in a sparse matrix is in fact a request |
560 to create this element so it can be filled. Therefore a piece of | |
6569 | 561 code like |
562 | |
563 @example | |
6577 | 564 @group |
565 SparseMatrix sm; | |
566 @dots{} | |
567 for (int j = 0; j < nc; j++) | |
568 for (int i = 0; i < nr; i++) | |
569 std::cerr << " (" << i << "," << j << "): " << sm(i,j) | |
570 << std::endl; | |
571 @end group | |
6569 | 572 @end example |
573 | |
574 is a great way of turning the sparse matrix into a dense one, and a | |
575 very slow way at that since it reallocates the sparse object at each | |
576 zero element in the matrix. | |
577 | |
578 An easy way of preventing the above from happening is to create a temporary | |
6571 | 579 constant version of the sparse matrix. Note that only the container for |
6569 | 580 the sparse matrix will be copied, while the actual representation of the |
6571 | 581 data will be shared between the two versions of the sparse matrix. So this |
582 is not a costly operation. For example, the above would become | |
6569 | 583 |
584 @example | |
6577 | 585 @group |
586 SparseMatrix sm; | |
587 @dots{} | |
588 const SparseMatrix tmp (sm); | |
589 for (int j = 0; j < nc; j++) | |
590 for (int i = 0; i < nr; i++) | |
591 std::cerr << " (" << i << "," << j << "): " << tmp(i,j) | |
592 << std::endl; | |
593 @end group | |
6569 | 594 @end example |
595 | |
596 Finally, as the sparse types aren't just represented as a contiguous | |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
597 block of memory, the @nospell{@code{fortran_vec}} method of the @code{Array<T>} |
6571 | 598 is not available. It is however replaced by three separate methods |
6569 | 599 @code{ridx}, @code{cidx} and @code{data}, that access the raw compressed |
600 column format that the Octave sparse matrices are stored in. | |
601 Additionally, these methods can be used in a manner similar to @code{elem}, | |
6571 | 602 to allow the matrix to be accessed or filled. However, in that case it is |
6569 | 603 up to the user to respect the sparse matrix compressed column format |
604 discussed previous. | |
605 | |
6572 | 606 @node Creating Sparse Matrices in Oct-Files |
607 @subsubsection Creating Sparse Matrices in Oct-Files | |
6569 | 608 |
6572 | 609 You have several alternatives for creating a sparse matrix. |
610 You can first create the data as three vectors representing the | |
6569 | 611 row and column indexes and the data, and from those create the matrix. |
6572 | 612 Or alternatively, you can create a sparse matrix with the appropriate |
6571 | 613 amount of space and then fill in the values. Both techniques have their |
6569 | 614 advantages and disadvantages. |
615 | |
6572 | 616 Here is an example of how to create a small sparse matrix with the first |
617 technique | |
6569 | 618 |
619 @example | |
6577 | 620 @group |
621 int nz = 4, nr = 3, nc = 4; | |
622 | |
623 ColumnVector ridx (nz); | |
624 ColumnVector cidx (nz); | |
625 ColumnVector data (nz); | |
6569 | 626 |
6577 | 627 ridx(0) = 0; ridx(1) = 0; ridx(2) = 1; ridx(3) = 2; |
628 cidx(0) = 0; cidx(1) = 1; cidx(2) = 3; cidx(3) = 3; | |
629 data(0) = 1; data(1) = 2; data(2) = 3; data(3) = 4; | |
6569 | 630 |
6577 | 631 SparseMatrix sm (data, ridx, cidx, nr, nc); |
632 @end group | |
6569 | 633 @end example |
634 | |
6572 | 635 @noindent |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8486
diff
changeset
|
636 which creates the matrix given in section |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8486
diff
changeset
|
637 @ref{Storage of Sparse Matrices}. Note that the compressed matrix |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8486
diff
changeset
|
638 format is not used at the time of the creation of the matrix itself, |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8486
diff
changeset
|
639 however it is used internally. |
6569 | 640 |
641 As previously mentioned, the values of the sparse matrix are stored | |
6571 | 642 in increasing column-major ordering. Although the data passed by the |
6569 | 643 user does not need to respect this requirement, the pre-sorting the |
644 data significantly speeds up the creation of the sparse matrix. | |
645 | |
646 The disadvantage of this technique of creating a sparse matrix is | |
6571 | 647 that there is a brief time where two copies of the data exists. Therefore |
6569 | 648 for extremely memory constrained problems this might not be the right |
649 technique to create the sparse matrix. | |
650 | |
651 The alternative is to first create the sparse matrix with the desired | |
6571 | 652 number of non-zero elements and then later fill those elements in. The |
653 easiest way to do this is | |
6569 | 654 |
6571 | 655 @example |
6577 | 656 @group |
657 int nz = 4, nr = 3, nc = 4; | |
658 SparseMatrix sm (nr, nc, nz); | |
659 sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4; | |
660 @end group | |
6569 | 661 @end example |
662 | |
6571 | 663 That creates the same matrix as previously. Again, although it is not |
6569 | 664 strictly necessary, it is significantly faster if the sparse matrix is |
665 created in this manner that the elements are added in column-major | |
6571 | 666 ordering. The reason for this is that if the elements are inserted |
6569 | 667 at the end of the current list of known elements then no element |
668 in the matrix needs to be moved to allow the new element to be | |
6571 | 669 inserted. Only the column indexes need to be updated. |
6569 | 670 |
671 There are a few further points to note about this technique of creating | |
6572 | 672 a sparse matrix. Firstly, it is possible to create a sparse matrix |
6571 | 673 with fewer elements than are actually inserted in the matrix. Therefore |
6569 | 674 |
6571 | 675 @example |
6577 | 676 @group |
677 int nz = 4, nr = 3, nc = 4; | |
678 SparseMatrix sm (nr, nc, 0); | |
679 sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4; | |
680 @end group | |
6569 | 681 @end example |
682 | |
6572 | 683 @noindent |
684 is perfectly valid. However it is a very bad idea. The reason is that | |
6569 | 685 as each new element is added to the sparse matrix the space allocated |
6571 | 686 to it is increased by reallocating the memory. This is an expensive |
6569 | 687 operation, that will significantly slow this means of creating a sparse |
6572 | 688 matrix. Furthermore, it is possible to create a sparse matrix with |
689 too much storage, so having @var{nz} above equaling 6 is also valid. | |
6569 | 690 The disadvantage is that the matrix occupies more memory than strictly |
691 needed. | |
692 | |
6572 | 693 It is not always easy to know the number of non-zero elements prior |
6571 | 694 to filling a matrix. For this reason the additional storage for the |
6569 | 695 sparse matrix can be removed after its creation with the |
6571 | 696 @dfn{maybe_compress} function. Furthermore, the maybe_compress can |
6569 | 697 deallocate the unused storage, but it can equally remove zero elements |
698 from the matrix. The removal of zero elements from the matrix is | |
699 controlled by setting the argument of the @dfn{maybe_compress} function | |
6572 | 700 to be @samp{true}. However, the cost of removing the zeros is high because it |
6571 | 701 implies resorting the elements. Therefore, if possible it is better |
702 is the user doesn't add the zeros in the first place. An example of | |
6569 | 703 the use of @dfn{maybe_compress} is |
704 | |
705 @example | |
6577 | 706 @group |
6569 | 707 int nz = 6, nr = 3, nc = 4; |
6577 | 708 |
6569 | 709 SparseMatrix sm1 (nr, nc, nz); |
710 sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4; | |
711 sm1.maybe_compress (); // No zero elements were added | |
712 | |
713 SparseMatrix sm2 (nr, nc, nz); | |
6571 | 714 sm2(0,0) = 1; sm2(0,1) = 2; sm(0,2) = 0; sm(1,2) = 0; |
6569 | 715 sm1(1,3) = 3; sm1(2,3) = 4; |
716 sm2.maybe_compress (true); // Zero elements were added | |
6577 | 717 @end group |
6569 | 718 @end example |
719 | |
720 The use of the @dfn{maybe_compress} function should be avoided if | |
721 possible, as it will slow the creation of the matrices. | |
722 | |
723 A third means of creating a sparse matrix is to work directly with | |
6571 | 724 the data in compressed row format. An example of this technique might |
6569 | 725 be |
726 | |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
727 @c Note the @verbatim environment is a relatively new addition to Texinfo. |
6571 | 728 @c Therefore use the @example environment and replace @, with @@, |
6569 | 729 @c { with @{, etc |
730 | |
731 @example | |
6577 | 732 octave_value arg; |
733 @dots{} | |
734 int nz = 6, nr = 3, nc = 4; // Assume we know the max no nz | |
735 SparseMatrix sm (nr, nc, nz); | |
736 Matrix m = arg.matrix_value (); | |
6569 | 737 |
6577 | 738 int ii = 0; |
739 sm.cidx (0) = 0; | |
740 for (int j = 1; j < nc; j++) | |
741 @{ | |
742 for (int i = 0; i < nr; i++) | |
743 @{ | |
744 double tmp = foo (m(i,j)); | |
745 if (tmp != 0.) | |
746 @{ | |
747 sm.data(ii) = tmp; | |
748 sm.ridx(ii) = i; | |
749 ii++; | |
750 @} | |
751 @} | |
752 sm.cidx(j+1) = ii; | |
753 @} | |
7081 | 754 sm.maybe_compress (); // If don't know a-priori |
755 // the final no of nz. | |
6569 | 756 @end example |
757 | |
6572 | 758 @noindent |
6569 | 759 which is probably the most efficient means of creating the sparse matrix. |
760 | |
761 Finally, it might sometimes arise that the amount of storage initially | |
6571 | 762 created is insufficient to completely store the sparse matrix. Therefore, |
6569 | 763 the method @code{change_capacity} exists to reallocate the sparse memory. |
6571 | 764 The above example would then be modified as |
6569 | 765 |
766 @example | |
6577 | 767 octave_value arg; |
768 @dots{} | |
769 int nz = 6, nr = 3, nc = 4; // Assume we know the max no nz | |
770 SparseMatrix sm (nr, nc, nz); | |
771 Matrix m = arg.matrix_value (); | |
6569 | 772 |
6577 | 773 int ii = 0; |
774 sm.cidx (0) = 0; | |
775 for (int j = 1; j < nc; j++) | |
776 @{ | |
777 for (int i = 0; i < nr; i++) | |
778 @{ | |
779 double tmp = foo (m(i,j)); | |
780 if (tmp != 0.) | |
781 @{ | |
782 if (ii == nz) | |
783 @{ | |
784 nz += 2; // Add 2 more elements | |
785 sm.change_capacity (nz); | |
786 @} | |
787 sm.data(ii) = tmp; | |
788 sm.ridx(ii) = i; | |
789 ii++; | |
790 @} | |
791 @} | |
792 sm.cidx(j+1) = ii; | |
793 @} | |
7081 | 794 sm.maybe_mutate (); // If don't know a-priori |
795 // the final no of nz. | |
6569 | 796 @end example |
797 | |
798 Note that both increasing and decreasing the number of non-zero elements in | |
6571 | 799 a sparse matrix is expensive, as it involves memory reallocation. Also as |
6569 | 800 parts of the matrix, though not its entirety, exist as the old and new copy |
6571 | 801 at the same time, additional memory is needed. Therefore if possible this |
6569 | 802 should be avoided. |
803 | |
6572 | 804 @node Using Sparse Matrices in Oct-Files |
6569 | 805 @subsubsection Using Sparse Matrices in Oct-Files |
806 | |
807 Most of the same operators and functions on sparse matrices that are | |
808 available from the Octave are equally available with oct-files. | |
809 The basic means of extracting a sparse matrix from an @code{octave_value} | |
810 and returning them as an @code{octave_value}, can be seen in the | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
811 following example. |
6569 | 812 |
813 @example | |
6577 | 814 @group |
815 octave_value_list retval; | |
6569 | 816 |
6577 | 817 SparseMatrix sm = args(0).sparse_matrix_value (); |
7081 | 818 SparseComplexMatrix scm = |
819 args(1).sparse_complex_matrix_value (); | |
6577 | 820 SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value (); |
821 @dots{} | |
822 retval(2) = sbm; | |
823 retval(1) = scm; | |
824 retval(0) = sm; | |
825 @end group | |
6569 | 826 @end example |
827 | |
828 The conversion to an octave-value is handled by the sparse | |
829 @code{octave_value} constructors, and so no special care is needed. | |
830 | |
831 @node Accessing Global Variables in Oct-Files | |
832 @subsection Accessing Global Variables in Oct-Files | |
833 | |
834 Global variables allow variables in the global scope to be | |
6571 | 835 accessed. Global variables can easily be accessed with oct-files using |
6569 | 836 the support functions @code{get_global_value} and |
6571 | 837 @code{set_global_value}. @code{get_global_value} takes two arguments, |
838 the first is a string representing the variable name to obtain. The | |
6569 | 839 second argument is a boolean argument specifying what to do in the case |
6571 | 840 that no global variable of the desired name is found. An example of the |
6569 | 841 use of these two functions is |
842 | |
9906 | 843 @example |
844 @EXAMPLEFILE(globaldemo.cc) | |
845 @end example | |
6569 | 846 |
847 An example of its use is | |
848 | |
849 @example | |
850 @group | |
851 global a b | |
852 b = 10; | |
853 globaldemo ("b") | |
854 @result{} 10 | |
855 globaldemo ("c") | |
856 @result{} "Global variable not found" | |
857 num2str (a) | |
858 @result{} 42 | |
859 @end group | |
860 @end example | |
861 | |
862 @node Calling Octave Functions from Oct-Files | |
863 @subsection Calling Octave Functions from Oct-Files | |
864 | |
865 There is often a need to be able to call another octave function from | |
866 within an oct-file, and there are many examples of such within octave | |
6571 | 867 itself. For example the @code{quad} function is an oct-file that |
6569 | 868 calculates the definite integral by quadrature over a user supplied |
869 function. | |
870 | |
6571 | 871 There are also many ways in which a function might be passed. It might |
872 be passed as one of | |
6569 | 873 |
874 @enumerate 1 | |
875 @item Function Handle | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
876 |
6569 | 877 @item Anonymous Function Handle |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
878 |
6569 | 879 @item Inline Function |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
880 |
6569 | 881 @item String |
882 @end enumerate | |
883 | |
884 The example below demonstrates an example that accepts all four means of | |
6571 | 885 passing a function to an oct-file. |
6569 | 886 |
9906 | 887 @example |
888 @EXAMPLEFILE(funcdemo.cc) | |
889 @end example | |
6569 | 890 |
891 The first argument to this demonstration is the user supplied function | |
892 and the following arguments are all passed to the user function. | |
893 | |
894 @example | |
895 @group | |
6572 | 896 funcdemo (@@sin,1) |
6569 | 897 @result{} 0.84147 |
6572 | 898 funcdemo (@@(x) sin(x), 1) |
6569 | 899 @result{} 0.84147 |
6572 | 900 funcdemo (inline ("sin(x)"), 1) |
6569 | 901 @result{} 0.84147 |
6572 | 902 funcdemo ("sin",1) |
6569 | 903 @result{} 0.84147 |
904 funcdemo (@@atan2, 1, 1) | |
905 @result{} 0.78540 | |
906 @end group | |
907 @end example | |
908 | |
909 When the user function is passed as a string, the treatment of the | |
6571 | 910 function is different. In some cases it is necessary to always have the |
6572 | 911 user supplied function as an @code{octave_function} object. In that |
912 case the string argument can be used to create a temporary function like | |
6569 | 913 |
914 @example | |
915 @group | |
6577 | 916 std::octave fcn_name = unique_symbol_name ("__fcn__"); |
917 std::string fname = "function y = "; | |
918 fname.append (fcn_name); | |
919 fname.append ("(x) y = "); | |
920 fcn = extract_function (args(0), "funcdemo", fcn_name, | |
921 fname, "; endfunction"); | |
922 @dots{} | |
923 if (fcn_name.length ()) | |
924 clear_function (fcn_name); | |
6569 | 925 @end group |
926 @end example | |
927 | |
6571 | 928 There are two important things to know in this case. The number of input |
6569 | 929 arguments to the user function is fixed, and in the above is a single |
930 argument, and secondly to avoid leaving the temporary function in the | |
931 Octave symbol table it should be cleared after use. | |
932 | |
933 @node Calling External Code from Oct-Files | |
934 @subsection Calling External Code from Oct-Files | |
935 | |
936 Linking external C code to Octave is relatively simple, as the C | |
6571 | 937 functions can easily be called directly from C++. One possible issue is |
6569 | 938 the declarations of the external C functions might need to be explicitly |
6571 | 939 defined as C functions to the compiler. If the declarations of the |
6569 | 940 external C functions are in the header @code{foo.h}, then the manner in |
941 which to ensure that the C++ compiler treats these declarations as C | |
942 code is | |
943 | |
944 @example | |
945 @group | |
946 #ifdef __cplusplus | |
6571 | 947 extern "C" |
6569 | 948 @{ |
949 #endif | |
950 #include "foo.h" | |
951 #ifdef __cplusplus | |
952 @} /* end extern "C" */ | |
953 #endif | |
954 @end group | |
955 @end example | |
956 | |
6571 | 957 Calling Fortran code however can pose some difficulties. This is due to |
6569 | 958 differences in the manner in compilers treat the linking of Fortran code |
6571 | 959 with C or C++ code. Octave supplies a number of macros that allow |
6569 | 960 consistent behavior across a number of compilers. |
961 | |
962 The underlying Fortran code should use the @code{XSTOPX} function to | |
6571 | 963 replace the Fortran @code{STOP} function. @code{XSTOPX} uses the Octave |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
964 exception handler to treat failing cases in the Fortran code |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
965 explicitly. Note that Octave supplies its own replacement @sc{blas} |
6569 | 966 @code{XERBLA} function, which uses @code{XSTOPX}. |
967 | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
968 If the underlying code calls @code{XSTOPX}, then the @w{@code{F77_XFCN}} |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
969 macro should be used to call the underlying Fortran function. The Fortran |
6569 | 970 exception state can then be checked with the global variable |
6572 | 971 @code{f77_exception_encountered}. If @code{XSTOPX} will not be called, |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
972 then the @w{@code{F77_FCN}} macro should be used instead to call the Fortran |
6569 | 973 code. |
974 | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
975 There is no harm in using @w{@code{F77_XFCN}} in all cases, except that for |
6569 | 976 Fortran code that is short running and executes a large number of times, |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
977 there is potentially an overhead in doing so. However, if @w{@code{F77_FCN}} |
6569 | 978 is used with code that calls @code{XSTOP}, Octave can generate a |
979 segmentation fault. | |
980 | |
981 An example of the inclusion of a Fortran function in an oct-file is | |
982 given in the following example, where the C++ wrapper is | |
983 | |
9906 | 984 @example |
985 @EXAMPLEFILE(fortdemo.cc) | |
986 @end example | |
6569 | 987 |
6572 | 988 @noindent |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
989 and the Fortran function is |
6569 | 990 |
9906 | 991 @example |
992 @EXAMPLEFILE(fortsub.f) | |
993 @end example | |
6569 | 994 |
995 This example demonstrates most of the features needed to link to an | |
996 external Fortran function, including passing arrays and strings, as well | |
6571 | 997 as exception handling. An example of the behavior of this function is |
6569 | 998 |
999 @example | |
1000 @group | |
6572 | 1001 [b, s] = fortdemo (1:3) |
6569 | 1002 @result{} |
1003 b = 1.00000 0.50000 0.33333 | |
1004 s = There are 3 values in the input vector | |
1005 [b, s] = fortdemo(0:3) | |
1006 error: fortsub:divide by zero | |
1007 error: exception encountered in Fortran subroutine fortsub_ | |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
1008 error: fortdemo: error in Fortran |
6569 | 1009 @end group |
1010 @end example | |
1011 | |
1012 @node Allocating Local Memory in Oct-Files | |
1013 @subsection Allocating Local Memory in Oct-Files | |
1014 | |
1015 Allocating memory within an oct-file might seem easy as the C++ | |
6571 | 1016 new/delete operators can be used. However, in that case care must be |
1017 taken to avoid memory leaks. The preferred manner in which to allocate | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
1018 memory for use locally is to use the @w{@code{OCTAVE_LOCAL_BUFFER}} macro. |
6572 | 1019 An example of its use is |
6569 | 1020 |
1021 @example | |
1022 OCTAVE_LOCAL_BUFFER (double, tmp, len) | |
1023 @end example | |
1024 | |
1025 that returns a pointer @code{tmp} of type @code{double *} of length | |
1026 @code{len}. | |
1027 | |
1028 @node Input Parameter Checking in Oct-Files | |
1029 @subsection Input Parameter Checking in Oct-Files | |
1030 | |
6580 | 1031 As oct-files are compiled functions they have the possibility of causing |
7001 | 1032 Octave to abort abnormally. It is therefore important that |
1033 each and every function has the minimum of parameter | |
6580 | 1034 checking needed to ensure that Octave behaves well. |
1035 | |
1036 The minimum requirement, as previously discussed, is to check the number | |
1037 of input arguments before using them to avoid referencing a non existent | |
1038 argument. However, it some case this might not be sufficient as the | |
6593 | 1039 underlying code imposes further constraints. For example an external |
6580 | 1040 function call might be undefined if the input arguments are not |
6593 | 1041 integers, or if one of the arguments is zero. Therefore, oct-files often |
6580 | 1042 need additional input parameter checking. |
1043 | |
1044 There are several functions within Octave that might be useful for the | |
6593 | 1045 purposes of parameter checking. These include the methods of the |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1046 octave_value class like @code{is_real_matrix}, etc., but equally include |
6593 | 1047 more specialized functions. Some of the more common ones are |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1048 demonstrated in the following example. |
6580 | 1049 |
9906 | 1050 @example |
1051 @EXAMPLEFILE(paramdemo.cc) | |
1052 @end example | |
6580 | 1053 |
1054 @noindent | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1055 An example of its use is: |
6580 | 1056 |
1057 @example | |
1058 @group | |
1059 paramdemo ([1, 2, NaN, Inf]) | |
1060 @result{} Properties of input array: | |
1061 includes Inf or NaN values | |
1062 includes other values than 1 and 0 | |
1063 includes only int, Inf or NaN values | |
1064 @end group | |
1065 @end example | |
6569 | 1066 |
1067 @node Exception and Error Handling in Oct-Files | |
1068 @subsection Exception and Error Handling in Oct-Files | |
1069 | |
1070 Another important feature of Octave is its ability to react to the user | |
6571 | 1071 typing @kbd{Control-C} even during calculations. This ability is based on the |
6569 | 1072 C++ exception handler, where memory allocated by the C++ new/delete |
6571 | 1073 methods are automatically released when the exception is treated. When |
6569 | 1074 writing an oct-file, to allow Octave to treat the user typing @kbd{Control-C}, |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1075 the @w{@code{OCTAVE_QUIT}} macro is supplied. For example: |
6569 | 1076 |
1077 @example | |
1078 @group | |
6577 | 1079 for (octave_idx_type i = 0; i < a.nelem (); i++) |
1080 @{ | |
1081 OCTAVE_QUIT; | |
1082 b.elem(i) = 2. * a.elem(i); | |
1083 @} | |
6569 | 1084 @end group |
1085 @end example | |
1086 | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1087 The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows |
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1088 Octave to treat the user request with the @kbd{Control-C}. Without this macro, |
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1089 the user must either wait for the function to return before the interrupt is |
6569 | 1090 processed, or press @kbd{Control-C} three times to force Octave to exit. |
1091 | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1092 The @w{@code{OCTAVE_QUIT}} macro does impose a very small speed penalty, and so |
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1093 for loops that are known to be small it might not make sense to include |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
1094 @w{@code{OCTAVE_QUIT}}. |
6569 | 1095 |
1096 When creating an oct-file that uses an external libraries, the function | |
1097 might spend a significant portion of its time in the external | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1098 library. It is not generally possible to use the @w{@code{OCTAVE_QUIT}} macro |
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1099 in this case. The alternative in this case is |
6569 | 1100 |
1101 @example | |
1102 @group | |
6577 | 1103 BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE; |
1104 @dots{} some code that calls a "foreign" function @dots{} | |
1105 END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE; | |
6569 | 1106 @end group |
1107 @end example | |
1108 | |
1109 The disadvantage of this is that if the foreign code allocates any | |
1110 memory internally, then this memory might be lost during an interrupt, | |
6571 | 1111 without being deallocated. Therefore, ideally Octave itself should |
6569 | 1112 allocate any memory that is needed by the foreign code, with either the |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
1113 @nospell{fortran_vec} method or the @w{@code{OCTAVE_LOCAL_BUFFER}} macro. |
6569 | 1114 |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
1115 The Octave unwind_protect mechanism (@ref{The @code{unwind_protect} Statement}) |
6571 | 1116 can also be used in oct-files. In conjunction with the exception |
6569 | 1117 handling of Octave, it is important to enforce that certain code is run |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1118 to allow variables, etc. to be restored even if an exception occurs. An |
6569 | 1119 example of the use of this mechanism is |
1120 | |
9906 | 1121 @example |
1122 @EXAMPLEFILE(unwinddemo.cc) | |
1123 @end example | |
6569 | 1124 |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1125 As can be seen in the example: |
6569 | 1126 |
1127 @example | |
1128 @group | |
6572 | 1129 unwinddemo (1, 0) |
6569 | 1130 @result{} Inf |
1131 1 / 0 | |
1132 @result{} warning: division by zero | |
6593 | 1133 Inf |
6569 | 1134 @end group |
1135 @end example | |
1136 | |
1137 The division by zero (and in fact all warnings) is disabled in the | |
1138 @code{unwinddemo} function. | |
1139 | |
1140 @node Documentation and Test of Oct-Files | |
1141 @subsection Documentation and Test of Oct-Files | |
1142 | |
6580 | 1143 The documentation of an oct-file is the fourth string parameter of the |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
1144 @w{@code{DEFUN_DLD}} macro. This string can be formatted in the same manner |
6580 | 1145 as the help strings for user functions (@ref{Documentation Tips}), |
1146 however there are some issue that are particular to the formatting of | |
1147 help strings within oct-files. | |
1148 | |
1149 The major issue is that the help string will typically be longer than a | |
1150 single line of text, and so the formatting of long help strings need to | |
7001 | 1151 be taken into account. There are several manners in which to treat this |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1152 issue, but the most common is illustrated in the following example, |
6580 | 1153 |
1154 @example | |
1155 @group | |
1156 DEFUN_DLD (do_what_i_want, args, nargout, | |
1157 "-*- texinfo -*-\n\ | |
1158 @@deftypefn @{Function File@} @{@} do_what_i_say (@@var@{n@})\n\ | |
7081 | 1159 A function that does what the user actually wants rather\n\ |
1160 than what they requested.\n\ | |
6580 | 1161 @@end deftypefn") |
1162 @{ | |
1163 @dots{} | |
1164 @} | |
1165 @end group | |
1166 @end example | |
1167 | |
1168 @noindent | |
1169 where, as can be seen, end line of text within the help string is | |
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8097
diff
changeset
|
1170 terminated by @code{\n\} which is an embedded new-line in the string |
6580 | 1171 together with a C++ string continuation character. Note that the final |
1172 @code{\} must be the last character on the line. | |
1173 | |
1174 Octave also includes the ability to embed the test and demonstration | |
1175 code for a function within the code itself (@ref{Test and Demo Functions}). | |
1176 This can be used from within oct-files (or in fact any file) with | |
1177 certain provisos. Firstly, the test and demo functions of Octave look | |
1178 for a @code{%!} as the first characters on a new-line to identify test | |
1179 and demonstration code. This is equally a requirement for | |
1180 oct-files. Furthermore the test and demonstration code must be included | |
1181 in a comment block of the compiled code to avoid it being interpreted by | |
6606 | 1182 the compiler. Finally, the Octave test and demonstration code must have |
6580 | 1183 access to the source code of the oct-file and not just the compiled code |
6606 | 1184 as the tests are stripped from the compiled code. An example in an |
6580 | 1185 oct-file might be |
1186 | |
1187 @example | |
1188 @group | |
1189 /* | |
1190 | |
1191 %!error (sin()) | |
1192 %!error (sin(1,1)) | |
1193 %!assert (sin([1,2]),[sin(1),sin(2)]) | |
1194 | |
1195 */ | |
1196 @end group | |
1197 @end example | |
6569 | 1198 |
6593 | 1199 @c @node Application Programming Interface for Oct-Files |
1200 @c @subsection Application Programming Interface for Oct-Files | |
1201 @c | |
1202 @c WRITE ME, using Coda section 1.3 as a starting point. | |
6569 | 1203 |
1204 @node Mex-Files | |
1205 @section Mex-Files | |
1206 @cindex mex-files | |
1207 @cindex mex | |
1208 | |
1209 Octave includes an interface to allow legacy mex-files to be compiled | |
6571 | 1210 and used with Octave. This interface can also be used to share code |
1211 between Octave and non Octave users. However, as mex-files expose the | |
6593 | 1212 internal API of an alternative product to Octave, and the internal |
6569 | 1213 structure of Octave is different to this product, a mex-file can never |
6571 | 1214 have the same performance in Octave as the equivalent oct-file. In |
6569 | 1215 particular to support the manner in which mex-files access the variables |
1216 passed to mex functions, there are a significant number of additional | |
6593 | 1217 copies of memory when calling or returning from a mex function. For |
1218 this reason, new code should be written using the oct-file interface | |
6569 | 1219 discussed above if possible. |
1220 | |
1221 @menu | |
6572 | 1222 * Getting Started with Mex-Files:: |
6580 | 1223 * Working with Matrices and Arrays in Mex-Files:: |
1224 * Character Strings in Mex-Files:: | |
1225 * Cell Arrays with Mex-Files:: | |
6572 | 1226 * Structures with Mex-Files:: |
1227 * Sparse Matrices with Mex-Files:: | |
6580 | 1228 * Calling Other Functions in Mex-Files:: |
6593 | 1229 @c * Application Programming Interface for Mex-Files:: |
6569 | 1230 @end menu |
1231 | |
1232 @node Getting Started with Mex-Files | |
1233 @subsection Getting Started with Mex-Files | |
1234 | |
1235 The basic command to build a mex-file is either @code{mkoctfile --mex} or | |
6571 | 1236 @code{mex}. The first can either be used from within Octave or from the |
8486 | 1237 command line. However, to avoid issues with the installation of other |
6569 | 1238 products, the use of the command @code{mex} is limited to within Octave. |
1239 | |
1240 @DOCSTRING(mex) | |
1241 | |
1242 @DOCSTRING(mexext) | |
1243 | |
1244 One important difference between the use of mex with other products and | |
1245 with Octave is that the header file "matrix.h" is implicitly included | |
6571 | 1246 through the inclusion of "mex.h". This is to avoid a conflict with the |
6569 | 1247 Octave file "Matrix.h" with operating systems and compilers that don't |
1248 distinguish between filenames in upper and lower case | |
1249 | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1250 Consider the short example: |
6569 | 1251 |
9906 | 1252 @example |
1253 @group | |
1254 @EXAMPLEFILE(firstmexdemo.c) | |
1255 @end group | |
1256 @end example | |
6569 | 1257 |
6593 | 1258 This simple example demonstrates the basics of writing a mex-file. The |
1259 entry point into the mex-file is defined by @code{mexFunction}. Note | |
6580 | 1260 that the function name is not explicitly included in the |
1261 @code{mexFunction} and so there can only be a single @code{mexFunction} | |
1262 entry point per-file. Also the name of the function is determined by the | |
1263 name of the mex-file itself. Therefore if the above function is in the | |
1264 file @file{firstmexdemo.c}, it can be compiled with | |
1265 | |
1266 @example | |
1267 mkoctfile --mex firstmexdemo.c | |
1268 @end example | |
1269 | |
1270 @noindent | |
1271 which creates a file @file{firstmexdemo.mex}. The function can then be run | |
1272 from Octave as | |
1273 | |
1274 @example | |
1275 @group | |
1276 firstmexdemo() | |
1277 @result{} 1.2346 | |
1278 @end group | |
1279 @end example | |
1280 | |
1281 It should be noted that the mex-file contains no help string for the | |
6593 | 1282 functions it contains. To document mex-files, there should exist an |
1283 m-file in the same directory as the mex-file itself. Taking the above as | |
6580 | 1284 an example, we would therefore have a file @file{firstmexdemo.m} that might |
1285 contain the text | |
1286 | |
1287 @example | |
1288 %FIRSTMEXDEMO Simple test of the functionality of a mex-file. | |
1289 @end example | |
1290 | |
1291 In this case, the function that will be executed within Octave will be | |
1292 given by the mex-file, while the help string will come from the | |
6593 | 1293 m-file. This can also be useful to allow a sample implementation of the |
6580 | 1294 mex-file within the Octave language itself for testing purposes. |
1295 | |
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8097
diff
changeset
|
1296 Although we cannot have multiple entry points into a single mex-file, |
6580 | 1297 we can use the @code{mexFunctionName} function to determine what name |
6593 | 1298 the mex-file was called with. This can be used to alter the behavior of |
1299 the mex-file based on the function name. For example if | |
6580 | 1300 |
9906 | 1301 @example |
1302 @group | |
1303 @EXAMPLEFILE(myfunc.c) | |
1304 @end group | |
1305 @end example | |
6580 | 1306 |
1307 @noindent | |
1308 is in file @file{myfunc.c}, and it is compiled with | |
1309 | |
1310 @example | |
1311 @group | |
1312 mkoctfile --mex myfunc.c | |
1313 ln -s myfunc.mex myfunc2.mex | |
1314 @end group | |
1315 @end example | |
1316 | |
1317 Then as can be seen by | |
1318 | |
1319 @example | |
1320 @group | |
1321 myfunc() | |
1322 @result{} You called function: myfunc | |
1323 This is the principal function | |
1324 myfunc2() | |
1325 @result{} You called function: myfunc2 | |
1326 @end group | |
1327 @end example | |
1328 | |
1329 @noindent | |
1330 the behavior of the mex-file can be altered depending on the functions | |
1331 name. | |
1332 | |
6593 | 1333 Allow the user should only include @code{mex.h} in their code, Octave |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1334 declares additional functions, typedefs, etc., available to the user to |
6593 | 1335 write mex-files in the headers @code{mexproto.h} and @code{mxarray.h}. |
1336 | |
6580 | 1337 @node Working with Matrices and Arrays in Mex-Files |
1338 @subsection Working with Matrices and Arrays in Mex-Files | |
1339 | |
6593 | 1340 The basic mex type of all variables is @code{mxArray}. All variables, |
1341 such as matrices, cell arrays or structures are all stored in this basic | |
6580 | 1342 type, and this type serves basically the same purpose as the |
6593 | 1343 octave_value class in oct-files. That is it acts as a container for the |
6580 | 1344 more specialized types. |
1345 | |
6593 | 1346 The @code{mxArray} structure contains at a minimum, the variable it |
1347 represents name, its dimensions, its type and whether the variable is | |
1348 real or complex. It can however contain a number of additional fields | |
1349 depending on the type of the @code{mxArray}. There are a number of | |
1350 functions to create @code{mxArray} structures, including | |
1351 @code{mxCreateCellArray}, @code{mxCreateSparse} and the generic | |
1352 @code{mxCreateNumericArray}. | |
1353 | |
1354 The basic functions to access the data contained in an array is | |
1355 @code{mxGetPr}. As the mex interface assumes that the real and imaginary | |
6939 | 1356 parts of a complex array are stored separately, there is an equivalent |
6593 | 1357 function @code{mxGetPi} that get the imaginary part. Both of these |
1358 functions are for use only with double precision matrices. There also | |
1359 exists the generic function @code{mxGetData} and @code{mxGetImagData} | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1360 that perform the same operation on all matrix types. For example: |
6593 | 1361 |
1362 @example | |
1363 @group | |
1364 mxArray *m; | |
6686 | 1365 mwSize *dims; |
6593 | 1366 UINT32_T *pr; |
1367 | |
6686 | 1368 dims = (mwSize *) mxMalloc (2 * sizeof(mwSize)); |
6593 | 1369 dims[0] = 2; |
1370 dims[1] = 2; | |
1371 m = mxCreateNumericArray (2, dims, mxUINT32_CLASS, mxREAL); | |
1372 pr = = (UINT32_T *) mxGetData (m); | |
1373 @end group | |
1374 @end example | |
1375 | |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1376 There are also the functions @code{mxSetPr}, etc., that perform the |
6593 | 1377 inverse, and set the data of an Array to use the block of memory pointed |
1378 to by the argument of @code{mxSetPr}. | |
1379 | |
6686 | 1380 Note the type @code{mwSize} used above, and @code{mwIndex} are defined |
1381 as the native precision of the indexing in Octave on the platform on | |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1382 which the mex-file is built. This allows both 32- and 64-bit platforms |
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1383 to support mex-files. @code{mwSize} is used to define array dimension |
6686 | 1384 and maximum number or elements, while @code{mwIndex} is used to define |
1385 indexing into arrays. | |
1386 | |
6593 | 1387 An example that demonstration how to work with arbitrary real or complex |
1388 double precision arrays is given by the file @file{mypow2.c} as given | |
1389 below. | |
1390 | |
9906 | 1391 @example |
1392 @EXAMPLEFILE(mypow2.c) | |
1393 @end example | |
6593 | 1394 |
1395 @noindent | |
1396 with an example of its use | |
1397 | |
1398 @example | |
1399 @group | |
1400 b = randn(4,1) + 1i * randn(4,1); | |
1401 all(b.^2 == mypow2(b)) | |
1402 @result{} 1 | |
1403 @end group | |
1404 @end example | |
1405 | |
1406 | |
7096 | 1407 The example above uses the functions @code{mxGetDimensions}, |
1408 @code{mxGetNumberOfElements}, and @code{mxGetNumberOfDimensions} to work | |
1409 with the dimensions of multi-dimensional arrays. The functions | |
1410 @code{mxGetM}, and @code{mxGetN} are also available to find the number | |
1411 of rows and columns in a matrix. | |
6580 | 1412 |
1413 @node Character Strings in Mex-Files | |
1414 @subsection Character Strings in Mex-Files | |
1415 | |
6593 | 1416 As mex-files do not make the distinction between single and double |
1417 quoted strings within Octave, there is perhaps less complexity in the | |
1418 use of strings and character matrices in mex-files. An example of their | |
1419 use, that parallels the demo in @file{stringdemo.cc}, is given in the | |
1420 file @file{mystring.c}, as seen below. | |
1421 | |
9906 | 1422 @example |
1423 @EXAMPLEFILE(mystring.c) | |
1424 @end example | |
6593 | 1425 |
1426 @noindent | |
1427 An example of its expected output is | |
1428 | |
1429 @example | |
1430 @group | |
1431 mystring(["First String"; "Second String"]) | |
1432 @result{} s1 = Second String | |
1433 First String | |
1434 @end group | |
1435 @end example | |
1436 | |
7096 | 1437 Other functions in the mex interface for handling character strings are |
1438 @code{mxCreateString}, @code{mxArrayToString}, and | |
1439 @code{mxCreateCharMatrixFromStrings}. In a mex-file, a character string | |
1440 is considered to be a vector rather than a matrix. This is perhaps an | |
1441 arbitrary distinction as the data in the mxArray for the matrix is | |
1442 consecutive in any case. | |
6580 | 1443 |
1444 @node Cell Arrays with Mex-Files | |
1445 @subsection Cell Arrays with Mex-Files | |
6569 | 1446 |
6593 | 1447 We can perform exactly the same operations in Cell arrays in mex-files |
1448 as we can in oct-files. An example that reduplicates the functional of | |
1449 the @file{celldemo.cc} oct-file in a mex-file is given by | |
1450 @file{mycell.c} as below | |
1451 | |
9906 | 1452 @example |
1453 @group | |
1454 @EXAMPLEFILE(mycell.c) | |
1455 @end group | |
1456 @end example | |
6593 | 1457 |
1458 @noindent | |
1459 which as can be seen below has exactly the same behavior as the oct-file | |
1460 version. | |
1461 | |
1462 @example | |
1463 @group | |
1464 [b1, b2, b3] = mycell (@{1, [1, 2], "test"@}) | |
1465 @result{} | |
1466 b1 = 1 | |
1467 b2 = | |
1468 | |
1469 1 2 | |
1470 | |
1471 b3 = test | |
1472 @end group | |
1473 @end example | |
1474 | |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1475 Note in the example the use of the @code{mxDuplicateArray} function. This |
6593 | 1476 is needed as the @code{mxArray} pointer returned by @code{mxGetCell} |
1477 might be deallocated. The inverse function to @code{mxGetCell} is | |
1478 @code{mcSetCell} and is defined as | |
1479 | |
1480 @example | |
1481 void mxSetCell (mxArray *ptr, int idx, mxArray *val); | |
1482 @end example | |
1483 | |
7007 | 1484 Finally, to create a cell array or matrix, the appropriate functions are |
6593 | 1485 |
1486 @example | |
1487 @group | |
1488 mxArray *mxCreateCellArray (int ndims, const int *dims); | |
1489 mxArray *mxCreateCellMatrix (int m, int n); | |
1490 @end group | |
1491 @end example | |
6569 | 1492 |
6572 | 1493 @node Structures with Mex-Files |
1494 @subsection Structures with Mex-Files | |
6569 | 1495 |
6593 | 1496 The basic function to create a structure in a mex-file is |
1497 @code{mxCreateStructMatrix}, which creates a structure array with a two | |
1498 dimensional matrix, or @code{mxCreateStructArray}. | |
1499 | |
1500 @example | |
1501 @group | |
7081 | 1502 mxArray *mxCreateStructArray (int ndims, int *dims, |
1503 int num_keys, | |
6593 | 1504 const char **keys); |
7081 | 1505 mxArray *mxCreateStructMatrix (int rows, int cols, |
1506 int num_keys, | |
6593 | 1507 const char **keys); |
1508 @end group | |
1509 @end example | |
1510 | |
1511 Accessing the fields of the structure can then be performed with the | |
1512 @code{mxGetField} and @code{mxSetField} or alternatively with the | |
1513 @code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions. | |
1514 | |
1515 @example | |
1516 @group | |
7081 | 1517 mxArray *mxGetField (const mxArray *ptr, mwIndex index, |
1518 const char *key); | |
6593 | 1519 mxArray *mxGetFieldByNumber (const mxArray *ptr, |
6686 | 1520 mwIndex index, int key_num); |
1521 void mxSetField (mxArray *ptr, mwIndex index, | |
6593 | 1522 const char *key, mxArray *val); |
6686 | 1523 void mxSetFieldByNumber (mxArray *ptr, mwIndex index, |
6593 | 1524 int key_num, mxArray *val); |
1525 @end group | |
1526 @end example | |
1527 | |
1528 A difference between the oct-file interface to structures and the | |
1529 mex-file version is that the functions to operate on structures in | |
1530 mex-files directly include an @code{index} over the elements of the | |
1531 arrays of elements per @code{field}. Whereas the oct-file structure | |
1532 includes a Cell Array per field of the structure. | |
1533 | |
1534 An example that demonstrates the use of structures in mex-file can be | |
1535 found in the file @file{mystruct.c}, as seen below | |
6580 | 1536 |
9906 | 1537 @example |
1538 @EXAMPLEFILE(mystruct.c) | |
1539 @end example | |
6580 | 1540 |
6593 | 1541 An example of the behavior of this function within Octave is then |
1542 | |
1543 @example | |
7081 | 1544 a(1).f1 = "f11"; a(1).f2 = "f12"; |
1545 a(2).f1 = "f21"; a(2).f2 = "f22"; | |
6593 | 1546 b = mystruct(a) |
1547 @result{} field f1(0) = f11 | |
1548 field f1(1) = f21 | |
1549 field f2(0) = f12 | |
1550 field f2(1) = f22 | |
1551 b = | |
1552 @{ | |
1553 this = | |
1554 | |
1555 (, | |
1556 [1] = this1 | |
1557 [2] = this2 | |
1558 [3] = this3 | |
1559 [4] = this4 | |
1560 ,) | |
1561 | |
1562 that = | |
1563 | |
1564 (, | |
1565 [1] = that1 | |
1566 [2] = that2 | |
1567 [3] = that3 | |
1568 [4] = that4 | |
1569 ,) | |
1570 | |
1571 @} | |
1572 @end example | |
6569 | 1573 |
1574 @node Sparse Matrices with Mex-Files | |
1575 @subsection Sparse Matrices with Mex-Files | |
1576 | |
6593 | 1577 The Octave format for sparse matrices is identical to the mex format in |
7001 | 1578 that it is a compressed column sparse format. Also in both, sparse |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
1579 matrices are required to be two-dimensional. The only difference is that |
6939 | 1580 the real and imaginary parts of the matrix are stored separately. |
6593 | 1581 |
1582 The mex-file interface, as well as using @code{mxGetM}, @code{mxGetN}, | |
1583 @code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi}, | |
1584 @code{mxSetPr} and @code{mxSetPi}, the mex-file interface supplies the | |
1585 functions | |
1586 | |
1587 @example | |
1588 @group | |
6686 | 1589 mwIndex *mxGetIr (const mxArray *ptr); |
1590 mwIndex *mxGetJc (const mxArray *ptr); | |
1591 mwSize mxGetNzmax (const mxArray *ptr); | |
6593 | 1592 |
6686 | 1593 void mxSetIr (mxArray *ptr, mwIndex *ir); |
1594 void mxSetJc (mxArray *ptr, mwIndex *jc); | |
1595 void mxSetNzmax (mxArray *ptr, mwSize nzmax); | |
6593 | 1596 @end group |
1597 @end example | |
6580 | 1598 |
6593 | 1599 @noindent |
1600 @code{mxGetNzmax} gets the maximum number of elements that can be stored | |
1601 in the sparse matrix. This is not necessarily the number of non-zero | |
1602 elements in the sparse matrix. @code{mxGetJc} returns an array with one | |
1603 additional value than the number of columns in the sparse matrix. The | |
1604 difference between consecutive values of the array returned by | |
1605 @code{mxGetJc} define the number of non-zero elements in each column of | |
1606 the sparse matrix. Therefore | |
6580 | 1607 |
6593 | 1608 @example |
1609 @group | |
6686 | 1610 mwSize nz, n; |
1611 mwIndex *Jc; | |
6593 | 1612 mxArray *m; |
1613 @dots{} | |
1614 n = mxGetN (m); | |
1615 Jc = mxGetJc (m); | |
1616 nz = Jc[n]; | |
1617 @end group | |
1618 @end example | |
1619 | |
1620 @noindent | |
1621 returns the actual number of non-zero elements stored in the matrix in | |
1622 @code{nz}. As the arrays returned by @code{mxGetPr} and @code{mxGetPi} | |
1623 only contain the non-zero values of the matrix, we also need a pointer | |
1624 to the rows of the non-zero elements, and this is given by | |
1625 @code{mxGetIr}. A complete example of the use of sparse matrices in | |
1626 mex-files is given by the file @file{mysparse.c} as seen below | |
1627 | |
9906 | 1628 @example |
1629 @EXAMPLEFILE(mysparse.c) | |
1630 @end example | |
6569 | 1631 |
6580 | 1632 @node Calling Other Functions in Mex-Files |
1633 @subsection Calling Other Functions in Mex-Files | |
1634 | |
1635 It is also possible call other Octave functions from within a mex-file | |
6593 | 1636 using @code{mexCallMATLAB}. An example of the use of |
6580 | 1637 @code{mexCallMATLAB} can be see in the example below |
1638 | |
9906 | 1639 @example |
1640 @EXAMPLEFILE(myfeval.c) | |
1641 @end example | |
6580 | 1642 |
1643 If this code is in the file @file{myfeval.c}, and is compiled to | |
1644 @file{myfeval.mex}, then an example of its use is | |
6569 | 1645 |
6580 | 1646 @example |
1647 @group | |
1648 myfeval("sin", 1) | |
1649 a = myfeval("sin", 1) | |
1650 @result{} Hello, World! | |
1651 I have 2 inputs and 1 outputs | |
1652 I'm going to call the interpreter function sin | |
1653 a = 0.84147 | |
1654 @end group | |
1655 @end example | |
1656 | |
1657 Note that it is not possible to use function handles or inline functions | |
1658 within a mex-file. | |
1659 | |
6593 | 1660 @c @node Application Programming Interface for Mex-Files |
1661 @c @subsection Application Programming Interface for Mex-Files | |
1662 @c | |
1663 @c WRITE ME, refer to mex.h and mexproto.h | |
6569 | 1664 |
1665 @node Standalone Programs | |
1666 @section Standalone Programs | |
1667 | |
1668 The libraries Octave itself uses, can be utilized in standalone | |
6571 | 1669 applications. These applications then have access, for example, to the |
6569 | 1670 array and matrix classes as well as to all the Octave algorithms. The |
1671 following C++ program, uses class Matrix from liboctave.a or | |
1672 liboctave.so. | |
1673 | |
9906 | 1674 @example |
1675 @group | |
1676 @EXAMPLEFILE(standalone.cc) | |
1677 @end group | |
1678 @end example | |
6569 | 1679 |
6580 | 1680 @noindent |
6569 | 1681 mkoctfile can then be used to build a standalone application with a |
1682 command like | |
1683 | |
1684 @example | |
1685 @group | |
8097
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1686 $ mkoctfile --link-stand-alone standalone.cc -o standalone |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1687 $ ./standalone |
6569 | 1688 Hello Octave world! |
1689 11 12 | |
1690 21 22 | |
1691 $ | |
1692 @end group | |
1693 @end example | |
1694 | |
1695 Note that the application @code{hello} will be dynamically linked | |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1696 against the octave libraries and any octave support libraries. The above |
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1697 allows the Octave math libraries to be used by an application. It does |
8097
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1698 not however allow the script files, oct-files or builtin functions of |
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1699 Octave to be used by the application. To do that the Octave interpreter |
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1700 needs to be initialized first. An example of how to do this can then be |
8097
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1701 seen in the code |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1702 |
9906 | 1703 @example |
1704 @group | |
1705 @EXAMPLEFILE(embedded.cc) | |
1706 @end group | |
1707 @end example | |
8097
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1708 |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1709 @noindent |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1710 which is compiled and run as before as a standalone application with |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1711 |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1712 @example |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1713 @group |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1714 $ mkoctfile --link-stand-alone embedded.cc -o embedded |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1715 $ ./embedded |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1716 GCD of [10, 15] is 5 |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1717 $ |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1718 @end group |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1719 @end example |
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1720 |