Mercurial > hg > octave-jordi

comparison doc/interpreter/external.txi @ 16867:be41c30bcb44

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