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