Mercurial > octave
view doc/interpreter/external.txi @ 32808:b81aef2c6d82 stable
doc: Expand on documentation of interfacing to Fortran code.
* doc/interpreter/external.txi: Remove recommendation of obsolete macro. Add
documentation for related preprocessor macros.
* examples/code/fortrandemo.cc: Don't use obsolete macro in example.
author | Markus Mützel <markus.muetzel@gmx.de> |
---|---|
date | Mon, 22 Jan 2024 19:16:08 +0100 |
parents | 2e484f9f1f18 |
children | aeb8f8438dd5 1a6cb4552775 |
line wrap: on
line source
@c Copyright (C) 2007-2024 The Octave Project Developers @c @c This file is part of Octave. @c @c Octave is free software: you can redistribute it and/or modify it @c under the terms of the GNU General Public License as published by @c the Free Software Foundation, either version 3 of the License, or @c (at your option) any later version. @c @c Octave is distributed in the hope that it will be useful, but @c WITHOUT ANY WARRANTY; without even the implied warranty of @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @c GNU General Public License for more details. @c @c You should have received a copy of the GNU General Public License @c along with Octave; see the file COPYING. If not, see @c <https://www.gnu.org/licenses/>. @node External Code Interface @appendix External Code Interface @cindex dynamic-linking @cindex Dynamically Linked Functions @cindex Octave API "The sum of human wisdom is not contained in any one language" --- Ezra Pound Octave is a fantastic language for solving many problems in science and engineering. However, it is not the only computer language and there are times when you may want to use code written in other languages. Good reasons for doing so include: 1) not re-inventing the wheel; existing function libraries which have been thoroughly tested and debugged or large scale simulation codebases are a good example, 2) accessing unique capabilities of a different language; for example the well-known regular expression functions of Perl (but don't do that because @code{regexp} already exists in Octave). Performance should generally @strong{not} be a reason for using compiled extensions. Although compiled extensions can run faster, particularly if they replace a loop in Octave code, this is almost never the best path to take. First, there are many techniques to speed up Octave performance while remaining within the language. Second, Octave is a high-level language that makes it easy to perform common mathematical tasks. Giving that up means shifting the focus from solving the real problem to solving a computer programming problem. It means returning to low-level constructs such as pointers, memory management, mathematical overflow/underflow, etc. Because of the low level nature, and the fact that the compiled code is executed outside of Octave, there is the very real possibility of crashing the interpreter and losing work. Before going further, you should first determine if you really need to bother writing code outside of Octave. @itemize @bullet @item Can I get the same functionality using the Octave scripting language alone? Even when a function already exists outside the language, it may be better to simply reproduce the behavior in an m-file rather than attempt to interface to the outside code. @item Is the code thoroughly optimized for Octave? If performance is an issue you should always start with the in-language techniques for getting better performance. Chief among these is vectorization (@pxref{Vectorization and Faster Code Execution}) which not only makes the code concise and more understandable but improves performance (10X-100X). If loops must be used, make sure that the allocation of space for variables takes place outside the loops using an assignment to a matrix of the right size, or zeros. @item Does the code make as much use as possible of existing built-in library routines? These routines are highly optimized and many do not carry the overhead of being interpreted. @item Does writing a dynamically linked function represent a useful investment of your time, relative to staying in Octave? It will take time to learn Octave's interface for external code and there will inevitably be issues with tools such as compilers. @end itemize With that said, Octave offers a versatile interface for including chunks of compiled code as dynamically linked extensions. These dynamically linked functions can be called from the interpreter in the same manner as any ordinary function. The interface is bi-directional and external code can call Octave functions (like @code{plot}) which otherwise might be very difficult to develop. The interface is centered around supporting the languages C++, C, and Fortran. Octave itself is written in C++ and can call external C++/C code through its native oct-file interface. The C language is also supported through the mex-file interface for compatibility with @sc{matlab}. Fortran code is easiest to reach through the oct-file interface. Because many other languages provide C or C++ APIs it is relatively simple to build bridges between Octave and other languages. This is also a way to bridge to hardware resources which often have device drivers written in C. @menu * Oct-Files:: * Mex-Files:: * Standalone Programs:: * Java Interface:: @end menu @node Oct-Files @section Oct-Files @cindex oct-files @cindex mkoctfile @cindex oct @menu * Getting Started with Oct-Files:: * Matrices and Arrays in Oct-Files:: * Character Strings in Oct-Files:: * Cell Arrays in Oct-Files:: * Structures in Oct-Files:: * Sparse Matrices in Oct-Files:: * Accessing Global Variables in Oct-Files:: * Calling Octave Functions from Oct-Files:: * Calling External Code from Oct-Files:: * Allocating Local Memory in Oct-Files:: * Input Parameter Checking in Oct-Files:: * Exception and Error Handling in Oct-Files:: * Documentation and Testing of Oct-Files:: @c * Application Programming Interface for Oct-Files:: @end menu @node Getting Started with Oct-Files @subsection Getting Started with Oct-Files Oct-files are pieces of C++ code that have been compiled with the Octave API into a dynamically loadable object. They take their name from the file which contains the object which has the extension @file{.oct}. Finding a C++ compiler, using the correct switches, adding the right include paths for header files, etc.@: is a difficult task. Octave automates this by providing the @code{mkoctfile} command with which to build oct-files. The command is available from within Octave or at the shell command line. @DOCSTRING(mkoctfile) Consider the following short example which introduces the basics of writing a C++ function that can be linked to Octave. @example @group @EXAMPLEFILE(helloworld.cc) @end group @end example The first critical line is @code{#include <octave/oct.h>} which makes available most of the definitions necessary for a C++ oct-file. Note that @file{octave/oct.h} is a C++ header and cannot be directly @code{#include}'ed in a C source file, nor any other language. Included by @file{oct.h} is a definition for the macro @w{@code{DEFUN_DLD}} which creates a dynamically loaded function. This macro takes four arguments: @enumerate 1 @item The function name as it will be seen in Octave, @item The list of arguments to the function of type @code{octave_value_list}, @item The number of output arguments, which can be---and often is---omitted if not used, and @item The string to use for the help text of the function. @end enumerate The return type of functions defined with @w{@code{DEFUN_DLD}} is always @code{octave_value_list}. There are a couple of important considerations in the choice of function name. First, it must be a valid Octave function name and so must be a sequence of letters, digits, and underscores not starting with a digit. Second, as Octave uses the function name to define the filename it attempts to find the function in, the function name in the @w{@code{DEFUN_DLD}} macro must match the filename of the oct-file. Therefore, the above function should be in a file @file{helloworld.cc}, and would be compiled to an oct-file using the command @example mkoctfile helloworld.cc @end example This will create a file called @file{helloworld.oct} that is the compiled version of the function. It should be noted that it is perfectly acceptable to have more than one @w{@code{DEFUN_DLD}} function in a source file. However, there must either be a symbolic link to the oct-file for each of the functions defined in the source code with the @w{@code{DEFUN_DLD}} macro or the @code{autoload} (@ref{Function Files}) function should be used. The rest of the function shows how to find the number of input arguments, how to print through the Octave pager, and how to return from the function. After compiling this function as above, an example of its use is @example @group helloworld (1, 2, 3) @print{} Hello World has 3 input arguments and 0 output arguments. @end group @end example Subsequent sections show how to use specific classes from Octave's core internals. Base classes like @code{dMatrix} (a matrix of double values) are found in the directory @file{liboctave/array}. The definitive reference for how to use a particular class is the header file itself. However, it is often enough simply to study the examples in the manual in order to be able to use a class. @node Matrices and Arrays in Oct-Files @subsection Matrices and Arrays in Oct-Files Octave supports a number of different array and matrix classes, the majority of which are based on the @code{Array} class. The exception are the sparse matrix types discussed separately below. There are three basic matrix types: @table @code @item Matrix A double precision matrix class defined in @file{dMatrix.h} @item ComplexMatrix A complex matrix class defined in @file{CMatrix.h} @item BoolMatrix A boolean matrix class defined in @file{boolMatrix.h} @end table These are the basic two-dimensional matrix types of Octave. In addition there are a number of multi-dimensional array types including @table @code @item NDArray A double precision array class defined in @file{dNDArray.h} @item ComplexNDarray A complex array class defined in @file{CNDArray.h} @item boolNDArray A boolean array class defined in @file{boolNDArray.h} @item int8NDArray @itemx int16NDArray @itemx int32NDArray @itemx int64NDArray 8, 16, 32, and 64-bit signed array classes defined in @file{int8NDArray.h}, @file{int16NDArray.h}, etc. @item uint8NDArray @itemx uint16NDArray @itemx uint32NDArray @itemx uint64NDArray 8, 16, 32, and 64-bit unsigned array classes defined in @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc. @end table There are several basic ways of constructing matrices or multi-dimensional arrays. Using the class @code{Matrix} as an example one can @itemize @bullet @item Create an empty matrix or array with the empty constructor. For example: @example Matrix a; @end example This can be used for all matrix and array types. @item Define the dimensions of the matrix or array with a dim_vector which has the same characteristics as the vector returned from @code{size}. For example: @example @group dim_vector dv (2, 3); // 2 rows, 3 columns Matrix a (dv); @end group @end example This can be used for all matrix and array types. @item Define the number of rows and columns in the matrix. For example: @example Matrix a (2, 2) @end example This constructor can @strong{only} be used with matrix types. @end itemize These types all share a number of basic methods and operators. Many bear a resemblance to functions that exist in the interpreter. A selection of useful methods include @deftypefn {Method} {T&} operator () (octave_idx_type) @deftypefnx {Method} {T&} elem (octave_idx_type) The @code{()} operator or @code{elem} method allow the values of the matrix or array to be read or set. These methods take a single argument, which is of type @code{octave_idx_type}, that is the index into the matrix or array. Additionally, the matrix type allows two argument versions of the @code{()} operator and @code{elem} method, giving the row and column index of the value to get or set. @end deftypefn Note that these functions do significant error checking and so in some circumstances the user might prefer to access the data of the array or matrix directly through the @code{fortran_vec} method discussed below. @deftypefn {Method} {octave_idx_type} numel () const The total number of elements in the matrix or array. @end deftypefn @deftypefn {Method} {size_t} byte_size () const The number of bytes used to store the matrix or array. @end deftypefn @deftypefn {Method} {dim_vector} dims () const The dimensions of the matrix or array in value of type @code{dim_vector}. @end deftypefn @deftypefn {Method} {int} ndims () const The number of dimensions of the matrix or array. Matrices are always 2-D, but arrays can be N-dimensional. @end deftypefn @deftypefn {Method} {void} resize (const dim_vector&) @deftypefnx {Method} {void} resize (nrows, ncols) A method taking either an argument of type @code{dim_vector}, or, in the case of a matrix, two arguments of type @code{octave_idx_type} defining the number of rows and columns in the matrix. @end deftypefn @deftypefn {Method} {T *} fortran_vec () This method returns a pointer to the underlying data of the matrix or array so that it can be manipulated directly, either within Octave or by an external library. @end deftypefn Operators such as @code{+}, @code{-}, or @code{*} can be used on the majority of the matrix and array types. In addition there are a number of methods that are of interest only for matrices such as @code{transpose}, @code{hermitian}, @code{solve}, etc. The typical way to extract a matrix or array from the input arguments of @w{@code{DEFUN_DLD}} function is as follows @example @group @EXAMPLEFILE(addtwomatrices.cc) @end group @end example To avoid segmentation faults causing Octave to abort, this function explicitly checks that there are sufficient arguments available before accessing these arguments. It then obtains two multi-dimensional arrays of type @code{NDArray} and adds these together. Note that the @code{array_value} method is called without using the @code{is_matrix_type} method. If an error occurs when attempting to extract the value, Octave will print a message and throw an exception. The reason to prefer this coding structure is that the arguments might be a type which is not an @code{NDArray}, but for which it would make sense to convert them to one. The @code{array_value} method allows this conversion to be performed transparently when possible. If you need to catch errors like this, and perform some kind of cleanup or other operation, you can catch the @code{octave_execution_error} exception. @code{A + B}, operating on two @code{NDArray} objects returns an @code{NDArray}, which is cast to an @code{octave_value} on the return from the function. An example of the use of this demonstration function is @example @group addtwomatrices (ones (2, 2), eye (2, 2)) @result{} 2 1 1 2 @end group @end example A list of the basic @code{Matrix} and @code{Array} types, the methods to extract these from an @code{octave_value}, and the associated header file is listed below. @multitable @columnfractions .3 .4 .3 @headitem Type @tab Function @tab Source Code @item @code{RowVector} @tab @code{row_vector_value} @tab @file{dRowVector.h} @item @code{ComplexRowVector} @tab @code{complex_row_vector_value} @tab @file{CRowVector.h} @item @code{ColumnVector} @tab @code{column_vector_value} @tab @file{dColVector.h} @item @code{ComplexColumnVector} @tab @code{complex_column_vector_value} @tab @file{CColVector.h} @item @code{Matrix} @tab @code{matrix_value} @tab @file{dMatrix.h} @item @code{ComplexMatrix} @tab @code{complex_matrix_value} @tab @file{CMatrix.h} @item @code{boolMatrix} @tab @code{bool_matrix_value} @tab @file{boolMatrix.h} @item @code{charMatrix} @tab @code{char_matrix_value} @tab @file{chMatrix.h} @item @code{NDArray} @tab @code{array_value} @tab @file{dNDArray.h} @item @code{ComplexNDArray} @tab @code{complex_array_value} @tab @file{CNDArray.h} @item @code{boolNDArray} @tab @code{bool_array_value} @tab @file{boolNDArray.h} @item @code{charNDArray} @tab @code{char_array_value} @tab @file{charNDArray.h} @item @code{int8NDArray} @tab @code{int8_array_value} @tab @file{int8NDArray.h} @item @code{int16NDArray} @tab @code{int16_array_value} @tab @file{int16NDArray.h} @item @code{int32NDArray} @tab @code{int32_array_value} @tab @file{int32NDArray.h} @item @code{int64NDArray} @tab @code{int64_array_value} @tab @file{int64NDArray.h} @item @code{uint8NDArray} @tab @code{uint8_array_value} @tab @file{uint8NDArray.h} @item @code{uint16NDArray} @tab @code{uint16_array_value} @tab @file{uint16NDArray.h} @item @code{uint32NDArray} @tab @code{uint32_array_value} @tab @file{uint32NDArray.h} @item @code{uint64NDArray} @tab @code{uint64_array_value} @tab @file{uint64NDArray.h} @end multitable @node Character Strings in Oct-Files @subsection Character Strings in Oct-Files A character string in Octave is just a special @code{Array} class. Consider the example: @example @EXAMPLEFILE(stringdemo.cc) @end example An example of the use of this function is @example @group s0 = ["First String"; "Second String"]; [s1,s2] = stringdemo (s0) @result{} s1 = Second String First String @result{} s2 = First String Second String typeinfo (s2) @result{} sq_string typeinfo (s1) @result{} string @end group @end example One additional complication of strings in Octave is the difference between single quoted and double quoted strings. To find out if an @code{octave_value} contains a single or double quoted string use one of the predicate tests shown below. @example @group if (args(0).is_sq_string ()) octave_stdout << "First argument is a single quoted string\n"; else if (args(0).is_dq_string ()) octave_stdout << "First argument is a double quoted string\n"; @end group @end example Note, however, that both types of strings are represented by the @code{charNDArray} type, and so when assigning to an @code{octave_value}, the type of string should be specified. For example: @example @group octave_value_list retval; charNDArray ch; @dots{} // Create single quoted string retval(1) = octave_value (ch); // default constructor is sq_string OR retval(1) = octave_value (ch, '\''); // explicitly create sq_string // Create a double quoted string retval(0) = octave_value (ch, '"'); @end group @end example @node Cell Arrays in Oct-Files @subsection Cell Arrays in Oct-Files Octave's cell type is also available from within oct-files. A cell array is just an @code{Array} of @code{octave_value}s, and thus each element of the cell array can be treated like any other @code{octave_value}. A simple example is @example @EXAMPLEFILE(celldemo.cc) @end example Note that cell arrays are used less often in standard oct-files and so the @file{Cell.h} header file must be explicitly included. The rest of the example extracts the @code{octave_value}s one by one from the cell array and returns them as individual output arguments. For example: @example @group [b1, b2, b3] = celldemo (@{1, [1, 2], "test"@}) @result{} b1 = 1 b2 = 1 2 b3 = test @end group @end example @node Structures in Oct-Files @subsection Structures in Oct-Files A structure in Octave is a map between a number of fields represented and their values. The Standard Template Library @code{map} class is used, with the pair consisting of a @code{std::string} and an Octave @code{Cell} variable. A simple example demonstrating the use of structures within oct-files is @example @EXAMPLEFILE(structdemo.cc) @end example An example of its use is @example @group x.a = 1; x.b = "test"; x.c = [1, 2]; structdemo (x, "b") @result{} selected = test @end group @end example The example above specifically uses the @code{octave_scalar_map} class which is for representing a single struct. For structure arrays, the @code{octave_map} class is used instead. The commented code shows how the demo could be modified to handle a structure array. In that case, the @code{contents} method returns a @code{Cell} which may have more than one element. Therefore, to obtain the underlying @code{octave_value} in the single struct example we would write @example octave_value tmp = arg0.contents (arg1)(0); @end example @noindent where the trailing @code{(0)} is the @code{()} operator on the @code{Cell} object. If this were a true structure array with multiple elements we could iterate over the elements using the @code{()} operator. Structures are a relatively complex data container and there are more functions available in @file{oct-map.h} which make coding with them easier than relying on just @code{contents}. @node Sparse Matrices in Oct-Files @subsection Sparse Matrices in Oct-Files There are three classes of sparse objects that are of interest to the user. @table @code @item SparseMatrix A double precision sparse matrix class @item SparseComplexMatrix A complex sparse matrix class @item SparseBoolMatrix A boolean sparse matrix class @end table All of these classes inherit from the @code{Sparse<T>} template class, and so all have similar capabilities and usage. The @code{Sparse<T>} class was based on Octave's @code{Array<T>} class and users familiar with Octave's @code{Array} classes will be comfortable with the use of the sparse classes. The sparse classes will not be entirely described in this section, due to their similarity with the existing @code{Array} classes. However, there are a few differences due the nature of sparse objects, and these will be described. First, although it is fundamentally possible to have N-dimensional sparse objects, the Octave sparse classes do not allow them at this time; All instances of the sparse classes @strong{must} be 2-dimensional. This means that @code{SparseMatrix} is actually more similar to Octave's @code{Matrix} class than it is to the @code{NDArray} class. @menu * Array and Sparse Class Differences:: * Creating Sparse Matrices in Oct-Files:: * Using Sparse Matrices in Oct-Files:: @end menu @node Array and Sparse Class Differences @subsubsection Array and Sparse Class Differences The number of elements in a sparse matrix is considered to be the number of nonzero elements, rather than the product of the dimensions. Therefore, @example @group SparseMatrix sm; @dots{} int nnz = sm.nelem (); @end group @end example @noindent returns the number of nonzero elements (like the interpreter function @code{nnz}). If the user really requires the number of elements in the matrix, including the nonzero elements, they should use @code{numel} rather than @code{nelem}. Note that for very large matrices, where the product of the two dimensions is larger than the representation of an unsigned int, @code{numel} can overflow. An example is @code{speye (1e6)} which will create a matrix with a million rows and columns, but only a million nonzero elements. In this case, the number of rows multiplied by the number of columns is more than two hundred times the maximum value that can be represented by an unsigned 32-bit int. The use of @code{numel} should, therefore, be avoided unless it is known that it will not overflow. Extreme care is also required when using the @code{elem} method or the @code{()} operator which perform essentially the same function. The reason is that if a sparse object is non-const, then Octave will assume that a request for a zero element in a sparse matrix is in fact a request to create this element so it can be filled. Therefore, a piece of code like @example @group SparseMatrix sm; @dots{} for (int j = 0; j < nc; j++) for (int i = 0; i < nr; i++) std::cerr << " (" << i << "," << j << "): " << sm(i,j) << "\n"; @end group @end example @noindent is a great way of turning a sparse matrix into a dense one, and a very slow way at that since it reallocates the sparse object for each zero element in the matrix. A simple way of preventing the above from happening is to create a temporary constant version of the sparse matrix. Note that only the container for the sparse matrix will be copied, while the actual representation of the data will be shared between the two versions of the sparse matrix; This is not a costly operation. The example above, re-written to prevent sparse-to-dense conversion, is @example @group SparseMatrix sm; @dots{} const SparseMatrix tmp (sm); for (int j = 0; j < nc; j++) for (int i = 0; i < nr; i++) std::cerr << " (" << i << "," << j << "): " << tmp(i,j) << "\n"; @end group @end example Finally, because the sparse types aren't represented by a contiguous block of memory, the @nospell{@code{fortran_vec}} method of @code{Array<T>} is not available. It is, however, replaced by three separate methods @code{ridx}, @code{cidx}, and @code{data}, that access the raw compressed column format that Octave sparse matrices are stored in. These methods can be used in a manner similar to @code{elem} to allow the matrix to be accessed or filled. However, it is up to the user to respect the sparse matrix compressed column format or the matrix will become corrupted. @node Creating Sparse Matrices in Oct-Files @subsubsection Creating Sparse Matrices in Oct-Files There are two useful strategies for creating a sparse matrix. The first is to create three vectors representing the row index, column index, and data values, and from these create the matrix. The second alternative is to create a sparse matrix with the appropriate amount of space, and then fill in the values. Both techniques have their advantages and disadvantages. Below is an example of creating a small sparse matrix using the first technique @example @group int nz, nr, nc; nz = 4, nr = 3, nc = 4; ColumnVector ridx (nz); ColumnVector cidx (nz); ColumnVector data (nz); ridx(0) = 1; cidx(0) = 1; data(0) = 1; ridx(1) = 2; cidx(1) = 2; data(1) = 2; ridx(2) = 2; cidx(2) = 4; data(2) = 3; ridx(3) = 3; cidx(3) = 4; data(3) = 4; SparseMatrix sm (data, ridx, cidx, nr, nc); @end group @end example @noindent which creates the matrix given in section @ref{Storage of Sparse Matrices}. Note that the compressed matrix format is not used at the time of the creation of the matrix itself, but is used internally. As discussed in the chapter on Sparse Matrices, the values of the sparse matrix are stored in increasing column-major ordering. Although the data passed by the user need not respect this requirement, pre-sorting the data will significantly speed up creation of the sparse matrix. The disadvantage of this technique for creating a sparse matrix is that there is a brief time when two copies of the data exist. For extremely memory constrained problems this may not be the best technique for creating a sparse matrix. The alternative is to first create a sparse matrix with the desired number of nonzero elements and then later fill those elements in. Sample code: @example @group int nz, nr, nc; nz = 4, nr = 3, nc = 4; SparseMatrix sm (nr, nc, nz); sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4; @end group @end example This creates the same matrix as previously. Again, although not strictly necessary, it is significantly faster if the sparse matrix is created and the elements are added in column-major ordering. The reason for this is that when elements are inserted at the end of the current list of known elements then no element in the matrix needs to be moved to allow the new element to be inserted; Only the column indices need to be updated. There are a few further points to note about this method of creating a sparse matrix. First, it is possible to create a sparse matrix with fewer elements than are actually inserted in the matrix. Therefore, @example @group int nr, nc; nr = 3, nc = 4; SparseMatrix sm (nr, nc, 0); sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4; @end group @end example @noindent is perfectly valid. However, it is a very bad idea because as each new element is added to the sparse matrix the matrix needs to request more space and reallocate memory. This is an expensive operation that will significantly slow this means of creating a sparse matrix. It is possible to create a sparse matrix with excess storage, so having @var{nz} greater than 4 in this example is also valid. The disadvantage is that the matrix occupies more memory than strictly needed. Of course, it is not always possible to know the number of nonzero elements prior to filling a matrix. For this reason the additional unused storage of a sparse matrix can be removed after its creation with the @code{maybe_compress} function. In addition to deallocating unused storage, @code{maybe_compress} can also remove zero elements from the matrix. The removal of zero elements from the matrix is controlled by setting the argument of the @code{maybe_compress} function to be @code{true}. However, the cost of removing the zeros is high because it implies re-sorting the elements. If possible, it is better for the user to avoid adding the unnecessary zeros in the first place. An example of the use of @code{maybe_compress} is @example @group int nz, nr, nc; nz = 6, nr = 3, nc = 4; SparseMatrix sm1 (nr, nc, nz); sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4; sm1.maybe_compress (); // No zero elements were added SparseMatrix sm2 (nr, nc, nz); sm2(0,0) = 1; sm2(0,1) = 2; sm(0,2) = 0; sm(1,2) = 0; sm1(1,3) = 3; sm1(2,3) = 4; sm2.maybe_compress (true); // Zero elements were added @end group @end example The use of the @code{maybe_compress} function should be avoided if possible as it will slow the creation of the matrix. A third means of creating a sparse matrix is to work directly with the data in compressed row format. An example of this advanced technique might be @example octave_value arg; @dots{} int nz, nr, nc; nz = 6, nr = 3, nc = 4; // Assume we know the max # nz SparseMatrix sm (nr, nc, nz); Matrix m = arg.matrix_value (); int ii = 0; sm.cidx (0) = 0; for (int j = 1; j < nc; j++) @{ for (int i = 0; i < nr; i++) @{ double tmp = m(i,j); if (tmp != 0.) @{ sm.data(ii) = tmp; sm.ridx(ii) = i; ii++; @} @} sm.cidx(j+1) = ii; @} sm.maybe_compress (); // If don't know a priori the final # of nz. @end example @noindent which is probably the most efficient means of creating a sparse matrix. Finally, it may sometimes arise that the amount of storage initially created is insufficient to completely store the sparse matrix. Therefore, the method @code{change_capacity} exists to reallocate the sparse memory. The above example would then be modified as @example octave_value arg; @dots{} int nz, nr, nc; nz = 6, nr = 3, nc = 4; // Guess the number of nz elements SparseMatrix sm (nr, nc, nz); Matrix m = arg.matrix_value (); int ii = 0; sm.cidx (0) = 0; for (int j = 1; j < nc; j++) @{ for (int i = 0; i < nr; i++) @{ double tmp = m(i,j); if (tmp != 0.) @{ if (ii == nz) @{ nz += 2; // Add 2 more elements sm.change_capacity (nz); @} sm.data(ii) = tmp; sm.ridx(ii) = i; ii++; @} @} sm.cidx(j+1) = ii; @} sm.maybe_compress (); // If don't know a priori the final # of nz. @end example Note that both increasing and decreasing the number of nonzero elements in a sparse matrix is expensive as it involves memory reallocation. Also because parts of the matrix, though not its entirety, exist as old and new copies at the same time, additional memory is needed. Therefore, if possible avoid changing capacity. @node Using Sparse Matrices in Oct-Files @subsubsection Using Sparse Matrices in Oct-Files Most of the same operators and functions for sparse matrices that are available from the Octave interpreter are also available within oct-files. The basic means of extracting a sparse matrix from an @code{octave_value}, and returning it as an @code{octave_value}, can be seen in the following example. @example @group octave_value_list retval; SparseMatrix sm = args(0).sparse_matrix_value (); SparseComplexMatrix scm = args(1).sparse_complex_matrix_value (); SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value (); @dots{} retval(2) = sbm; retval(1) = scm; retval(0) = sm; @end group @end example The conversion to an @code{octave_value} is handled by the sparse @code{octave_value} constructors, and so no special care is needed. @node Accessing Global Variables in Oct-Files @subsection Accessing Global Variables in Oct-Files Global variables allow variables in the global scope to be accessed. Global variables can be accessed within oct-files by using the support functions @w{@code{global_varval}} and @w{@code{global_assign}} from the current interpreter's symbol table. Both functions take as first argument a string representing the variable name to be obtained or assigned. The second argument of @w{@code{global_assign}} is the value to be assigned. An example of the use of these two functions is @example @EXAMPLEFILE(globaldemo.cc) @end example An example of its use is @example @group global a b b = 10; globaldemo ("b") @result{} 10 globaldemo ("c") @result{} "Global variable not found" num2str (a) @result{} 42 @end group @end example @node Calling Octave Functions from Oct-Files @subsection Calling Octave Functions from Oct-Files There is often a need to be able to call another Octave function from within an oct-file, and there are many examples of such within Octave itself. For example, the @code{quad} function is an oct-file that calculates the definite integral by quadrature over a user-supplied function. There are also many ways in which a function could be given as input. It might be passed as one of @enumerate 1 @item Function Handle @item Anonymous Function Handle @item String @end enumerate The code below demonstrates all four methods of passing a function to an oct-file. @example @EXAMPLEFILE(funcdemo.cc) @end example The first input to the demonstration code is a user-supplied function and the remaining arguments are all passed to the function. @example @group funcdemo (@@sin, 1) @result{} 0.84147 funcdemo (@@(x) sin (x), 1) @result{} 0.84147 funcdemo ("sin", 1) @result{} 0.84147 funcdemo (@@atan2, 1, 1) @result{} 0.78540 @end group @end example When the user function is passed as a string the treatment of the function is different. In some cases it is necessary to have the user supplied function as an @code{octave_function} object. In that case the string argument can be used to create a temporary function as demonstrated below. @example @group std::octave fcn_name = unique_symbol_name ("__fcn__"); std::string fcode = "function y = "; fcode.append (fcn_name); fcode.append ("(x) y = "); fcn = extract_function (args(0), "funcdemo", fcn_name, fcode, "; endfunction"); @dots{} if (fcn_name.length ()) clear_function (fcn_name); @end group @end example There are two important things to know in this case. First, the number of input arguments to the user function is fixed, and in the above example is a single argument. Second, to avoid leaving the temporary function in the Octave symbol table it should be cleared after use. Also, by convention all internal function names begin and end with the character sequence @samp{__}. @node Calling External Code from Oct-Files @subsection Calling External Code from Oct-Files Linking external C code to Octave is relatively simple, as the C functions can easily be called directly from C++. One possible issue is that the declarations of the external C functions may need to be explicitly defined as C functions to the compiler. If the declarations of the external C functions are in the header @file{foo.h}, then the tactic to ensure that the C++ compiler treats these declarations as C code is @example @group #ifdef __cplusplus extern "C" @{ #endif #include "foo.h" #ifdef __cplusplus @} /* end extern "C" */ #endif @end group @end example When calling functions that are implemented in Fortran code, some pecularities have to be taken into account. Symbol names in Fortran are case-insensitive, and depending on the used Fortran compiler, function names are either exported with all lower-case or with all upper-case characters. Additionally, some compilers append none, one or two underscores "@code{_}" at the end of exported function names. This is called "name-mangling". Octave supplies macros that allow writing code that automatically handles the name-mangling for a number of different Fortran compilers. These macros are @code{F77_FUNC} and @code{F77_FUNC_}. The former should be used for Fortran functions that do not contain any underscores in their name. The latter should be used for Fortran functions with underscores in their names. Both macros take two arguments: The first is the Fortran function name in all lower-case characters. The second is the same Fortran function name in all upper-case characters. Additionally to the name-mangling, different compilers are using different calling conventions for some types. Octave defines the following preprocessor macros to allow writing code that can be used with different Fortran calling conventions. Note that we don't attempt to handle Fortran functions, we always use subroutine wrappers for them and pass the return value as an extra argument. Use the following macros to pass character strings from C to Fortran: @example @group F77_CHAR_ARG(x) F77_CONST_CHAR_ARG(x) F77_CXX_STRING_ARG(x) F77_CHAR_ARG_LEN(l) F77_CHAR_ARG_DECL F77_CONST_CHAR_ARG_DECL F77_CHAR_ARG_LEN_DECL @end group @end example Use the following macros to write C-language functions that accept Fortran-style character strings: @example @group F77_CHAR_ARG_DEF(s, len) F77_CONST_CHAR_ARG_DEF(s, len) F77_CHAR_ARG_LEN_DEF(len) F77_CHAR_ARG_USE(s) F77_CHAR_ARG_LEN_USE(s, len) @end group @end example Use the following macros for Fortran types in C++ code: @table @code @item F77_INT4 Equivalent to Fortran @code{INTEGER*4} type @item F77_DBLE Equivalent to Fortran @code{DOUBLE PRECISION} type @item F77_REAL Equivalent to Fortran @code{REAL} type @item F77_CMPLX Equivalent to Fortran @code{COMPLEX} type @item F77_DBLE_CMPLX Equivalent to Fortran @code{DOUBLE COMPLEX} type @item F77_LOGICAL Equivalent to Fortran @code{LOGICAL} type @item F77_RET_T Return type of a C++ function that acts like a Fortran subroutine. @end table Use the following macros to return from C-language functions that are supposed to act like Fortran subroutines. @code{F77_NORETURN} is intended to be used as the last statement of such a function that has been tagged with a @qcode{"noreturn"} attribute. @example @group F77_RETURN(retval) F77_NORETURN(retval) @end group @end example The underlying Fortran code should use the @code{XSTOPX} function to replace the Fortran @code{STOP} function. @code{XSTOPX} uses the Octave exception handler to treat failing cases in the Fortran code explicitly. Note that Octave supplies its own replacement @sc{blas} @code{XERBLA} function, which uses @code{XSTOPX}. The following example shows the inclusion of a Fortran function in an oct-file, where the C++ wrapper is @example @EXAMPLEFILE(fortrandemo.cc) @end example @noindent and the Fortran function is @example @EXAMPLEFILE(fortransub.f) @end example This example demonstrates most of the features needed to link to an external Fortran function, including passing arrays and strings, as well as exception handling. Both the Fortran and C++ files need to be compiled in order for the example to work. @example @group mkoctfile fortrandemo.cc fortransub.f [b, s] = fortrandemo (1:3) @result{} b = 1.00000 0.50000 0.33333 s = There are 3 values in the input vector [b, s] = fortrandemo (0:3) error: fortrandemo: fortransub: divide by zero @end group @end example @node Allocating Local Memory in Oct-Files @subsection Allocating Local Memory in Oct-Files Allocating memory within an oct-file might seem easy, as the C++ new/delete operators can be used. However, in that case great care must be taken to avoid memory leaks. The preferred manner in which to allocate memory for use locally is to use the @w{@code{OCTAVE_LOCAL_BUFFER}} macro. An example of its use is @example OCTAVE_LOCAL_BUFFER (double, tmp, len) @end example @noindent that returns a pointer @code{tmp} of type @code{double *} of length @code{len}. In this case, Octave itself will worry about reference counting and variable scope and will properly free memory without programmer intervention. @node Input Parameter Checking in Oct-Files @subsection Input Parameter Checking in Oct-Files Because oct-files are compiled functions they open up the possibility of crashing Octave through careless function calls or memory faults. It is quite important that each and every function have a sufficient level of parameter checking to ensure that Octave behaves well. The minimum requirement, as previously discussed, is to check the number of input arguments before using them to avoid referencing a nonexistent argument. However, in some cases this might not be sufficient as the underlying code imposes further constraints. For example, an external function call might be undefined if the input arguments are not integers, or if one of the arguments is zero, or if the input is complex and a real value was expected. Therefore, oct-files often need additional input parameter checking. There are several functions within Octave that can be useful for the purposes of parameter checking. These include the methods of the @code{octave_value} class like @code{is_real_matrix}, @code{is_numeric_type}, etc. (see @file{ov.h}). Often, with a knowledge of the Octave m-file language, you can guess at what the corresponding C++ routine will. In addition there are some more specialized input validation functions of which a few are demonstrated below. @example @EXAMPLEFILE(paramdemo.cc) @end example @noindent An example of its use is: @example @group paramdemo ([1, 2, NaN, Inf]) @result{} Properties of input array: includes Inf or NaN values includes other values than 1 and 0 includes only int, Inf or NaN values @end group @end example @node Exception and Error Handling in Oct-Files @subsection Exception and Error Handling in Oct-Files Another important feature of Octave is its ability to react to the user typing @key{Control-C} during extended calculations. This ability is based on the C++ exception handler, where memory allocated by the C++ new/delete methods is automatically released when the exception is treated. When writing an oct-file which may run for a long time the programmer must periodically use the macro @w{@code{OCTAVE_QUIT}}, in order to allow Octave to check and possibly respond to a user typing @key{Control-C}. For example: @example @group for (octave_idx_type i = 0; i < a.nelem (); i++) @{ OCTAVE_QUIT; b.elem (i) = 2. * a.elem (i); @} @end group @end example The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows Octave to detect and acknowledge a @key{Control-C} key sequence. Without this macro, the user must either wait for the oct-file function to return before the interrupt is processed, or the user must press @key{Control-C} three times which will force Octave to exit completely. The @w{@code{OCTAVE_QUIT}} macro does impose a very small performance penalty; For loops that are known to be small it may not make sense to include @w{@code{OCTAVE_QUIT}}. When creating an oct-file that uses an external library, the function might spend a significant portion of its time in the external library. It is not generally possible to use the @w{@code{OCTAVE_QUIT}} macro in this case. The alternative code in this case is @example @group BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE; @dots{} some code that calls a "foreign" function @dots{} END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE; @end group @end example The disadvantage of this is that if the foreign code allocates any memory internally, then this memory might be lost during an interrupt, without being deallocated. Therefore, ideally Octave itself should allocate any memory that is needed by the foreign code, with either the @nospell{@code{fortran_vec}} method or the @w{@code{OCTAVE_LOCAL_BUFFER}} macro. The Octave @code{unwind_protect} mechanism (@ref{The unwind_protect Statement}) can also be used in oct-files. In conjunction with the exception handling of Octave, it ensures that certain recovery code is always run even if an exception occurs. An example of the use of this mechanism is @example @EXAMPLEFILE(unwinddemo.cc) @end example As can be seen in the example: @example @group unwinddemo (1, 0) @result{} Inf 1 / 0 @result{} warning: division by zero Inf @end group @end example The warning for division by zero (and in fact all warnings) are disabled in the @code{unwinddemo} function. @node Documentation and Testing of Oct-Files @subsection Documentation and Testing of Oct-Files The documentation for an oct-file is contained in the fourth string parameter of the @w{@code{DEFUN_DLD}} macro. This string can be formatted in the same manner as the help strings for user functions, however there are some issues that are particular to the formatting of help strings within oct-files. The major issue is that the help string will typically be longer than a single line of text, and so the formatting of long multi-line help strings needs to be taken into account. There are several possible solutions, but the most common is illustrated in the following example, @example @group DEFUN_DLD (do_what_i_want, args, nargout, "-*- texinfo -*-\n\ @@deftypefn @{@} @{@} do_what_i_say (@@var@{n@})\n\ A function that does what the user actually wants rather\n\ than what they requested.\n\ @@end deftypefn") @{ @dots{} @} @end group @end example @noindent where each line of text is terminated by @code{\n\} which is an embedded newline in the string together with a C++ string continuation character. Note that the final @code{\} must be the last character on the line. Octave also includes the ability to embed test and demonstration code for a function within the code itself (@pxref{Test and Demo Functions}). This can be used from within oct-files (or in fact any file) with certain provisos. First, the test and demo functions of Octave look for @code{%!} as the first two characters of a line to identify test and demonstration code. This is a requirement for oct-files as well. In addition, the test and demonstration code must be wrapped in a comment block to avoid it being interpreted by the compiler. Finally, the Octave test and demonstration code must have access to the original source code of the oct-file---not just the compiled code---as the tests are stripped from the compiled code. An example in an oct-file might be @example @group /* %!assert (sin ([1,2]), [sin(1),sin(2)]) %!error (sin ()) %!error (sin (1,1)) */ @end group @end example @c @node Application Programming Interface for Oct-Files @c @subsection Application Programming Interface for Oct-Files @c @c WRITE ME, using Coda section 1.3 as a starting point. @node Mex-Files @section Mex-Files @cindex mex-files @cindex mex Octave includes an interface to allow legacy mex-files to be compiled and used with Octave. This interface can also be used to share compiled code between Octave and @sc{matlab} users. However, as mex-files expose @sc{matlab}'s internal API, and the internal structure of Octave is different, a mex-file can never have the same performance in Octave as the equivalent oct-file. In particular, to support the manner in which variables are passed to mex functions there are a significant number of additional copies of memory blocks when invoking or returning from a mex-file function. For this reason, it is recommended that any new code be written with the oct-file interface previously discussed. @menu * Getting Started with Mex-Files:: * Working with Matrices and Arrays in Mex-Files:: * Character Strings in Mex-Files:: * Cell Arrays with Mex-Files:: * Structures with Mex-Files:: * Sparse Matrices with Mex-Files:: * Calling Other Functions in Mex-Files:: @c * Application Programming Interface for Mex-Files:: @end menu @node Getting Started with Mex-Files @subsection Getting Started with Mex-Files The basic command to build a mex-file is either @code{mkoctfile --mex} or @code{mex}. The first command can be used either from within Octave or from the command line. To avoid issues with @sc{matlab}'s own @code{mex} command, the use of the command @code{mex} is limited to within Octave. Compiled mex-files have the extension @file{.mex}. @DOCSTRING(mex) @DOCSTRING(mexext) Consider the following short example: @example @group @EXAMPLEFILE(myhello.c) @end group @end example The first line @code{#include "mex.h"} makes available all of the definitions necessary for a mex-file. One important difference between Octave and @sc{matlab} is that the header file @qcode{"matrix.h"} is implicitly included through the inclusion of @qcode{"mex.h"}. This is necessary to avoid a conflict with the Octave file @qcode{"Matrix.h"} for operating systems and compilers that don't distinguish between filenames in upper and lower case. The entry point into the mex-file is defined by @code{mexFunction}. The function takes four arguments: @enumerate 1 @item The number of return arguments (# of left-hand side args). @item An array of pointers to return arguments. @item The number of input arguments (# of right-hand side args). @item An array of pointers to input arguments. @end enumerate Note that the function name definition is not explicitly included in @code{mexFunction} and so there can only be a single @code{mexFunction} entry point per file. Instead, the name of the function as seen in Octave is determined by the name of the mex-file itself minus the extension. If the above function is in the file @file{myhello.c}, it can be compiled with @example mkoctfile --mex myhello.c @end example @noindent which creates a file @file{myhello.mex}. The function can then be run from Octave as @example @group myhello (1,2,3) @result{} Hello, World! @result{} I have 3 inputs and 0 outputs @end group @end example It should be noted that the mex-file contains no help string. To document mex-files, there should exist an m-file in the same directory as the mex-file itself. Taking the above as an example, there would need to be a file @file{myhello.m} which might contain the text @example %MYHELLO Simple test of the functionality of a mex-file. @end example In this case, the function that will be executed within Octave will be given by the mex-file, while the help string will come from the m-file. This can also be useful to allow a sample implementation of the mex-file within the Octave language itself for testing purposes. Although there cannot be multiple entry points in a single mex-file, one can use the @code{mexFunctionName} function to determine what name the mex-file was called with. This can be used to alter the behavior of the mex-file based on the function name. For example, if @example @group @EXAMPLEFILE(myfunc.c) @end group @end example @noindent is in the file @file{myfunc.c}, and is compiled with @example @group mkoctfile --mex myfunc.c ln -s myfunc.mex myfunc2.mex @end group @end example @noindent then as can be seen by @example @group myfunc () @result{} You called function: myfunc This is the principal function myfunc2 () @result{} You called function: myfunc2 @end group @end example @noindent the behavior of the mex-file can be altered depending on the function's name. Although the user should only include @file{mex.h} in their code, Octave declares additional functions, typedefs, etc., available to the user to write mex-files in the headers @file{mexproto.h} and @file{mxarray.h}. @node Working with Matrices and Arrays in Mex-Files @subsection Working with Matrices and Arrays in Mex-Files The basic mex type of all variables is @code{mxArray}. Any object, such as a matrix, cell array, or structure, is stored in this basic type. @code{mxArray} serves essentially the same purpose as the @code{octave_value} class in oct-files in that it acts as a container for all the more specialized types. The @code{mxArray} structure contains at a minimum, the name of the variable it represents, its dimensions, its type, and whether the variable is real or complex. It can also contain a number of additional fields depending on the type of the @code{mxArray}. There are a number of functions to create @code{mxArray} structures, including @code{mxCreateDoubleMatrix}, @code{mxCreateCellArray}, @code{mxCreateSparse}, and the generic @code{mxCreateNumericArray}. The basic function to access the data in an array is @code{mxGetPr}. Because the mex interface assumes that real and imaginary parts of a complex array are stored separately, there is an equivalent function @code{mxGetPi} that gets the imaginary part. Both of these functions are only for use with double precision matrices. The generic functions @code{mxGetData} and @code{mxGetImagData} perform the same operation for all matrix types. For example: @example @group mxArray *m; mwSize *dims; UINT32_T *pr; dims = (mwSize *) mxMalloc (2 * sizeof (mwSize)); dims[0] = 2; dims[1] = 2; m = mxCreateNumericArray (2, dims, mxUINT32_CLASS, mxREAL); pr = (UINT32_T *) mxGetData (m); @end group @end example There are also the functions @code{mxSetPr}, etc., that perform the inverse, and set the data of an array to use the block of memory pointed to by the argument of @code{mxSetPr}. Note the type @code{mwSize} used above, and also @code{mwIndex}, are defined as the native precision of the indexing in Octave on the platform on which the mex-file is built. This allows both 32- and 64-bit platforms to support mex-files. @code{mwSize} is used to define array dimensions and the maximum number or elements, while @code{mwIndex} is used to define indexing into arrays. An example that demonstrates how to work with arbitrary real or complex double precision arrays is given by the file @file{mypow2.c} shown below. @example @EXAMPLEFILE(mypow2.c) @end example @noindent An example of its use is @example @group b = randn (4,1) + 1i * randn (4,1); all (b.^2 == mypow2 (b)) @result{} 1 @end group @end example The example above uses the functions @code{mxGetDimensions}, @code{mxGetNumberOfElements}, and @code{mxGetNumberOfDimensions} to work with the dimensions of multi-dimensional arrays. The functions @code{mxGetM}, and @code{mxGetN} are also available to find the number of rows and columns in a 2-D matrix (@nospell{MxN} matrix). @node Character Strings in Mex-Files @subsection Character Strings in Mex-Files As mex-files do not make the distinction between single and double quoted strings that Octave does, there is perhaps less complexity in the use of strings and character matrices. An example of their use that parallels the demo in @file{stringdemo.cc} is given in the file @file{mystring.c}, as shown below. @example @EXAMPLEFILE(mystring.c) @end example @noindent An example of its expected output is @example @group mystring (["First String"; "Second String"]) @result{} Second String First String @end group @end example Other functions in the mex interface for handling character strings are @code{mxCreateString}, @code{mxArrayToString}, and @code{mxCreateCharMatrixFromStrings}. In a mex-file, a character string is considered to be a vector rather than a matrix. This is perhaps an arbitrary distinction as the data in the @code{mxArray} for the matrix is consecutive in any case. @node Cell Arrays with Mex-Files @subsection Cell Arrays with Mex-Files One can perform exactly the same operations on Cell arrays in mex-files as in oct-files. An example that duplicates the function of the @file{celldemo.cc} oct-file in a mex-file is given by @file{mycell.c} as shown below. @example @EXAMPLEFILE(mycell.c) @end example @noindent The output is identical to the oct-file version as well. @example @group [b1, b2, b3] = mycell (@{1, [1, 2], "test"@}) @result{} b1 = 1 b2 = 1 2 b3 = test @end group @end example Note in the example the use of the @code{mxDuplicateArray} function. This is needed as the @code{mxArray} pointer returned by @code{mxGetCell} might be deallocated. The inverse function to @code{mxGetCell}, used for setting Cell values, is @code{mxSetCell} and is defined as @example void mxSetCell (mxArray *ptr, int idx, mxArray *val); @end example Finally, to create a cell array or matrix, the appropriate functions are @example @group mxArray *mxCreateCellArray (int ndims, const int *dims); mxArray *mxCreateCellMatrix (int m, int n); @end group @end example @node Structures with Mex-Files @subsection Structures with Mex-Files The basic function to create a structure in a mex-file is @code{mxCreateStructMatrix} which creates a structure array with a two dimensional matrix, or @code{mxCreateStructArray}. @example @group mxArray *mxCreateStructArray (int ndims, int *dims, int num_keys, const char **keys); mxArray *mxCreateStructMatrix (int rows, int cols, int num_keys, const char **keys); @end group @end example Accessing the fields of the structure can then be performed with @code{mxGetField} and @code{mxSetField} or alternatively with the @code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions. @example @group mxArray *mxGetField (const mxArray *ptr, mwIndex index, const char *key); mxArray *mxGetFieldByNumber (const mxArray *ptr, mwIndex index, int key_num); void mxSetField (mxArray *ptr, mwIndex index, const char *key, mxArray *val); void mxSetFieldByNumber (mxArray *ptr, mwIndex index, int key_num, mxArray *val); @end group @end example A difference between the oct-file interface to structures and the mex-file version is that the functions to operate on structures in mex-files directly include an @code{index} over the elements of the arrays of elements per @code{field}; Whereas, the oct-file structure includes a Cell Array per field of the structure. An example that demonstrates the use of structures in a mex-file can be found in the file @file{mystruct.c} shown below. @example @EXAMPLEFILE(mystruct.c) @end example An example of the behavior of this function within Octave is then @example @group a(1).f1 = "f11"; a(1).f2 = "f12"; a(2).f1 = "f21"; a(2).f2 = "f22"; b = mystruct (a); @result{} field f1(0) = f11 field f1(1) = f21 field f2(0) = f12 field f2(1) = f22 b @result{} 2x2 struct array containing the fields: this that b(3) @result{} scalar structure containing the fields: this = this3 that = that3 @end group @end example @node Sparse Matrices with Mex-Files @subsection Sparse Matrices with Mex-Files The Octave format for sparse matrices is identical to the mex format in that it is a compressed column sparse format. Also, in both implementations sparse matrices are required to be two-dimensional. The only difference of importance to the programmer is that the real and imaginary parts of the matrix are stored separately. The mex-file interface, in addition to using @code{mxGetM}, @code{mxGetN}, @code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi}, @code{mxSetPr}, and @code{mxSetPi}, also supplies the following functions. @example @group mwIndex *mxGetIr (const mxArray *ptr); mwIndex *mxGetJc (const mxArray *ptr); mwSize mxGetNzmax (const mxArray *ptr); void mxSetIr (mxArray *ptr, mwIndex *ir); void mxSetJc (mxArray *ptr, mwIndex *jc); void mxSetNzmax (mxArray *ptr, mwSize nzmax); @end group @end example @noindent @code{mxGetNzmax} gets the maximum number of elements that can be stored in the sparse matrix. This is not necessarily the number of nonzero elements in the sparse matrix. @code{mxGetJc} returns an array with one additional value than the number of columns in the sparse matrix. The difference between consecutive values of the array returned by @code{mxGetJc} define the number of nonzero elements in each column of the sparse matrix. Therefore, @example @group mwSize nz, n; mwIndex *Jc; mxArray *m; @dots{} n = mxGetN (m); Jc = mxGetJc (m); nz = Jc[n]; @end group @end example @noindent returns the actual number of nonzero elements stored in the matrix in @code{nz}. As the arrays returned by @code{mxGetPr} and @code{mxGetPi} only contain the nonzero values of the matrix, we also need a pointer to the rows of the nonzero elements, and this is given by @code{mxGetIr}. A complete example of the use of sparse matrices in mex-files is given by the file @file{mysparse.c} shown below. @example @EXAMPLEFILE(mysparse.c) @end example A sample usage of @code{mysparse} is @example @group sm = sparse ([1, 0; 0, pi]); mysparse (sm) @result{} Matrix is 2-by-2 real sparse matrix with 2 elements last nonzero element (2, 2) = 3.14159 @end group @end example @node Calling Other Functions in Mex-Files @subsection Calling Other Functions in Mex-Files It is possible to call other Octave functions from within a mex-file using @code{mexCallMATLAB}. An example of the use of @code{mexCallMATLAB} can be see in the example below. @example @EXAMPLEFILE(myfeval.c) @end example If this code is in the file @file{myfeval.c}, and is compiled to @file{myfeval.mex}, then an example of its use is @example @group a = myfeval ("sin", 1) @result{} Starting file myfeval.mex I have 2 inputs and 1 outputs I'm going to call the interpreter function sin a = 0.84147 @end group @end example Note that it is not possible to use function handles within a mex-file. @c @node Application Programming Interface for Mex-Files @c @subsection Application Programming Interface for Mex-Files @c @c WRITE ME, refer to mex.h and mexproto.h @node Standalone Programs @section Standalone Programs The libraries Octave uses itself can be utilized in standalone applications. These applications then have access, for example, to the array and matrix classes, as well as to all of the Octave algorithms. The following C++ program, uses class Matrix from @file{liboctave.a} or @file{liboctave.so}. @example @EXAMPLEFILE(standalone.cc) @end example @noindent mkoctfile can be used to build a standalone application with a command like @example @group $ mkoctfile --link-stand-alone standalone.cc -o standalone $ ./standalone Hello Octave world! 11 12 21 22 $ @end group @end example Note that the application @code{standalone} will be dynamically linked against the Octave libraries and any Octave support libraries. The above allows the Octave math libraries to be used by an application. It does not, however, allow the script files, oct-files, or built-in functions of Octave to be used by the application. To do that, the Octave interpreter needs to be initialized first. An example of how to do this can then be seen in the code @example @EXAMPLEFILE(embedded.cc) @end example @noindent which, as before, is compiled and run as a standalone application with @example @group $ mkoctfile --link-stand-alone embedded.cc -o embedded $ ./embedded GCD of [10, 15] is 5 $ @end group @end example It is worth re-iterating that, if only built-in functions are to be called from a C++ standalone program then it does not need to initialize the interpreter. The general rule is that for a built-in function named @code{function_name} in the interpreter, there will be a C++ function named @code{Ffunction_name} (note the prepended capital @code{F}) accessible in the C++ API@. The declarations for all built-in functions are collected in the header file @code{builtin-defun-decls.h}. This feature should be used with care as the list of built-in functions can change. No guarantees can be made that a function that is currently a built-in won't be implemented as a @file{.m} file or as a dynamically linked function in the future. An example of how to call built-in functions from C++ can be seen in the code @example @EXAMPLEFILE(standalonebuiltin.cc) @end example @noindent which is compiled and run as a standalone application with @example @group $ mkoctfile --link-stand-alone standalonebuiltin.cc -o standalonebuiltin $ ./standalonebuiltin This is a matrix: 11 12 21 22 This is the norm of the matrix: 34.4952 $ @end group @end example @node Java Interface @section Java Interface @cindex using Octave with Java @cindex Java, using with Octave @cindex calling Java from Octave @cindex Java, calling from Octave @cindex calling Octave from Java @cindex Octave, calling from Java The Java Interface is designed for calling Java functions from within Octave. If you want to do the reverse, and call Octave from within Java, try a library like @code{joPas} (@url{http://jopas.sourceforge.net}). @menu * Making Java Classes Available:: * How to use Java from within Octave:: * Set up the JVM:: * Java Interface Functions:: @end menu @node Making Java Classes Available @subsection Making Java Classes Available @c - index - @cindex classpath, setting @cindex classpath, difference between static and dynamic @cindex static classpath @cindex dynamic classpath @cindex @file{javaclasspath.txt} @cindex @file{classpath.txt} @cindex classes, making available to Octave @c - index - Java finds classes by searching a @var{classpath} which is a list of Java archive files and/or directories containing class files. In Octave the @var{classpath} is composed of two parts: @itemize @item the @var{static classpath} is initialized once at startup of the JVM, and @item the @var{dynamic classpath} which can be modified at runtime. @end itemize Octave searches the @var{static classpath} first, and then the @var{dynamic classpath}. Classes appearing in the @var{static classpath}, as well as in the @var{dynamic classpath}, will therefore be found in the @var{static classpath} and loaded from this location. Classes which will be used frequently, or must be available to all users, should be added to the @var{static classpath}. The @var{static classpath} is populated once from the contents of a plain text file named @file{javaclasspath.txt} (or @file{classpath.txt} historically) when the Java Virtual Machine starts. This file contains one line for each individual classpath to be added to the @var{static classpath}. These lines can identify directories containing class files, or Java archives with complete class file hierarchies. Comment lines starting with a @samp{#} or a @samp{%} character are ignored. The search rules for the file @file{javaclasspath.txt} (or @file{classpath.txt}) are: @itemize @item First, Octave tries to locate it in the current directory (where Octave was started from). If such a file is found, it is read and defines the initial @var{static classpath}. Thus, it is possible to define a static classpath on a 'per Octave invocation' basis. @item Next, Octave searches in the user's home directory. If a file @file{javaclasspath.txt} exists here, its contents are appended to the static classpath (if any). Thus, it is possible to build an initial static classpath on a @nospell{'per user'} basis. @item Finally, Octave looks for a @file{javaclasspath.txt} in the m-file directory where Octave Java functions live. This is where the function @file{javaclasspath.m} resides, usually something like @file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}. You can find this directory by executing the command @example which javaclasspath @end example If this file exists here, its contents are also appended to the @var{static classpath}. Note that the archives and class directories defined in this last step will affect all users. @end itemize Classes which are used only by a specific script should be placed in the @var{dynamic classpath}. This portion of the classpath can be modified at runtime using the @code{javaaddpath} and @code{javarmpath} functions. Example: @example octave> base_path = "C:/Octave/java_files"; octave> # add two JAR archives to the dynamic classpath octave> javaaddpath ([base_path, "/someclasses.jar"]); octave> javaaddpath ([base_path, "/moreclasses.jar"]); octave> # check the dynamic classpath octave> p = javaclasspath; octave> disp (p@{1@}); C:/Octave/java_files/someclasses.jar octave> disp (p@{2@}); C:/Octave/java_files/moreclasses.jar octave> # remove the first element from the classpath octave> javarmpath ([base_path, "/someclasses.jar"]); octave> p = javaclasspath; octave> disp (p@{1@}); C:/Octave/java_files/moreclasses.jar octave> # provoke an error octave> disp (p@{2@}); error: A(I): Index exceeds matrix dimension. @end example Another way to add files to the @var{dynamic classpath} exclusively for your user account is to use the file @file{.octaverc} which is stored in your home directory. All Octave commands in this file are executed each time you start a new instance of Octave. The following example adds the directory @file{octave} to Octave's search path and the archive @file{myclasses.jar} in this directory to the Java search path. @example @group # contents of .octaverc: addpath ("~/octave"); javaaddpath ("~/octave/myclasses.jar"); @end group @end example @c ------------------------------------------------------------------------ @node How to use Java from within Octave @subsection How to use Java from within Octave The function @ref{XREFjavaObject,javaObject,javaObject} creates Java objects. In fact it invokes the public constructor of the class with the given name and with the given parameters. The following example shows how to invoke the constructors @code{BigDecimal(double)} and @code{BigDecimal(String)} of the builtin Java class @code{java.math.BigDecimal}. @example @group javaObject ("java.math.BigDecimal", 1.001 ); javaObject ("java.math.BigDecimal", "1.001"); @end group @end example Note that parameters of the Octave type @code{double} are implicitly converted into the Java type @code{double} and the Octave type (array of) @code{char} is converted into the java type @code{String}. A Java object created by @ref{XREFjavaObject,javaObject,javaObject} is never automatically converted into an Octave type but remains a Java object. It can be assigned to an Octave variable. @example @group a = 1.001; b = javaObject ("java.math.BigDecimal", a); @end group @end example Using @ref{XREFisjava,isjava,isjava}, it is possible to check whether a variable is a Java object and its class can be determined as well. In addition to the previous example: @example @group isjava (a) @result{} ans = 0 class (a) @result{} ans = double isjava (b) @result{} ans = 1 class (b) @result{} ans = java.math.BigDecimal @end group @end example The example above can be carried out using only Java objects: @example @group a = javaObject ("java.lang.Double", 1.001); b = javaObject ("java.math.BigDecimal", a); isjava (a) @result{} ans = 1 class (a) @result{} ans = java.lang.Double isjava (b) @result{} ans = 1 class (b) @result{} ans = java.math.BigDecimal @end group @end example One can see, that even a @code{java.lang.Double} is not converted to an Octave @code{double}, when created by @ref{XREFjavaObject,javaObject,javaObject}. But ambiguities might arise, if the Java classes @code{java.lang.Double} or @code{double} are parameters of a method (or a constructor). In this case they can be converted into one another, depending on the context. Via @ref{XREFjavaObject,javaObject,javaObject} one may create all kinds of Java objects but arrays. The latter are created through @ref{XREFjavaArray,javaArray,javaArray}. It is possible to invoke public member methods on Java objects in Java syntax: @example @group a.toString @result{} ans = 1.001 b.toString @result{} ans = 1.000999999999999889865... @end group @end example The second result may be surprising, but simply comes from the fact, that @code{1.001} cannot exactly be represented as @code{double}, due to rounding. Note that unlike in Java, in Octave methods without arguments can be invoked with and without parentheses @code{()}. Currently it is not possible to invoke static methods with a Java like syntax from within Octave. Instead, one has to use the function @ref{XREFjavaMethod,javaMethod,javaMethod} as in the following example: @example @group java.math.BigDecimal.valueOf(1.001); # does not work javaMethod ("valueOf", "java.math.BigDecimal", 1.001); # workaround @end group @end example As mentioned before, method and constructor parameters are converted automatically between Octave and Java types, if appropriate. For functions this is also true with return values, whereas for constructors this is not. It is also possible to access public fields of Java objects from within Octave using Java syntax, with the limitation of static fields: @example @group java.math.BigDecimal.ONE; # does not work java_get ("java.math.BigDecimal", "ONE"); # workaround @end group @end example Accordingly, with @ref{XREFjava_set,java_set,java_set} the value of a field can be set. Note that only public Java fields are accessible from within Octave. The following example indicates that in Octave empty brackets @code{[]} represent Java's @code{null} value and how Java exceptions are represented. @example @group javaObject ("java.math.BigDecimal", []); @result{} error: [java] java.lang.NullPointerException @end group @end example It is not recommended to represent Java's @code{null} value by empty brackets @code{[]}, because @code{null} has no type whereas @code{[]} has type @code{double}. In Octave it is possible to provide limited Java reflection by listing the public fields and methods of a Java object, both static or not. @example @group fieldnames (<Java object>) methods (<Java object>) @end group @end example Finally, an examples is shown how to access the stack trace from within Octave, where the function @ref{XREFdebug_java,debug_java,debug_java} is used to set and to get the current debug state. In debug mode, the Java error and the stack trace are displayed. @example @group debug_java (true) # use "false" to omit display of stack trace debug_java () @result{} ans = 1 javaObject ("java.math.BigDecimal", "1") ... .divide (javaObject ("java.math.BigDecimal", "0")) @end group @end example @node Set up the JVM @subsection Set up the JVM @cindex memory, limitations on JVM @cindex select JVM version In order to execute Java code Octave creates a Java Virtual Machine (JVM). By default the version of the JVM is used that was detected during configuration on Unix-like systems or that is pointed to from the registry keys at @file{HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\JRE} or @file{HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment} on Windows. The default path to the JVM can be overridden by setting the environment variable @w{@env{JAVA_HOME}} to the path where the JVM is installed. On Windows that might be, for example, @file{C:\Program Files\Java\jre-10.0.2}. Make sure that you select a directory that contains the JVM with a @nospell{bit-ness} that matches Octave's. The JVM is only loaded once per Octave session. Thus, to change the used version of the JVM, you might have to re-start Octave. To check which version of the JVM is currently being used, run @code{version -java}. The JVM allocates a fixed amount of initial memory and may expand this pool up to a fixed maximum memory limit. The default values depend on the Java version (@pxref{XREFjavamem,,javamem}). The memory pool is shared by all Java objects running in the JVM@. This strict memory limit is intended mainly to avoid runaway applications inside web browsers or in enterprise servers which can consume all memory and crash the system. When the maximum memory limit is hit, Java code will throw exceptions so that applications will fail or behave unexpectedly. You can specify options for the creation of the JVM inside a file named @file{java.opts}. This is a text file where enter you enter lines containing @option{-X} and @option{-D} options that are then passed to the JVM during initialization. The directory where the Java options file is located is specified by the environment variable @w{@env{OCTAVE_JAVA_DIR}}. If unset the directory where @file{javaclasspath.m} resides is used instead (typically @file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}). You can find this directory by executing @example which javaclasspath @end example The @option{-X} options allow you to increase the maximum amount of memory available to the JVM@. The following example allows up to 256 Megabytes to be used by adding the following line to the @file{java.opts} file: @example -Xmx256m @end example The maximum possible amount of memory depends on your system. On a Windows system with 2 Gigabytes main memory you should be able to set this maximum to about 1 Gigabyte. If your application requires a large amount of memory from the beginning, you can also specify the initial amount of memory allocated to the JVM@. Adding the following line to the @file{java.opts} file starts the JVM with 64 Megabytes of initial memory: @example -Xms64m @end example For more details on the available @option{-X} options of your Java Virtual Machine issue the command @samp{java -X} at the operating system command prompt and consult the Java documentation. The @option{-D} options can be used to define system properties which can then be used by Java classes inside Octave. System properties can be retrieved by using the @code{getProperty()} methods of the @code{java.lang.System} class. The following example line defines the property @var{MyProperty} and assigns it the string @code{12.34}. @example -DMyProperty=12.34 @end example The value of this property can then be retrieved as a string by a Java object or in Octave: @example @group octave> javaMethod ("getProperty", "java.lang.System", "MyProperty"); ans = 12.34 @end group @end example @node Java Interface Functions @subsection Java Interface Functions The following functions are the core of the Java Interface. They provide a way to create a Java object, get and set its data fields, and call Java methods which return results to Octave. @cindex object, creating a Java object @cindex instance, creating a Java instance @DOCSTRING(javaObject) @cindex array, creating a Java array @DOCSTRING(javaArray) There are many different variable types in Octave, but only ones created through @code{javaObject} can use Java functions. Before using Java with an unknown object the type can be checked with @code{isjava}. @DOCSTRING(isjava) Once an object has been created it is natural to find out what fields the object has, and to read (get) and write (set) them. @cindex fields, displaying available fields of a Java object In Octave the @code{fieldnames} function for structures has been overloaded to return the fields of a Java object. For example: @example @group dobj = javaObject ("java.lang.Double", pi); fieldnames (dobj) @result{} @{ [1,1] = public static final double java.lang.Double.POSITIVE_INFINITY [1,2] = public static final double java.lang.Double.NEGATIVE_INFINITY [1,3] = public static final double java.lang.Double.NaN [1,4] = public static final double java.lang.Double.MAX_VALUE [1,5] = public static final double java.lang.Double.MIN_NORMAL [1,6] = public static final double java.lang.Double.MIN_VALUE [1,7] = public static final int java.lang.Double.MAX_EXPONENT [1,8] = public static final int java.lang.Double.MIN_EXPONENT [1,9] = public static final int java.lang.Double.SIZE [1,10] = public static final java.lang.Class java.lang.Double.TYPE @} @end group @end example @cindex field, returning value of Java object field The analogy of objects with structures is carried over into reading and writing object fields. To read a field the object is indexed with the @samp{.} operator from structures. This is the preferred method for reading fields, but Octave also provides a function interface to read fields with @code{java_get}. An example of both styles is shown below. @example @group dobj = javaObject ("java.lang.Double", pi); dobj.MAX_VALUE @result{} 1.7977e+308 java_get ("java.lang.Float", "MAX_VALUE") @result{} 3.4028e+38 @end group @end example @DOCSTRING(java_get) @cindex field, setting value of Java object field @DOCSTRING(java_set) @cindex methods, displaying available methods of a Java object To see what functions can be called with an object use @code{methods}. For example, using the previously created @var{dobj}: @example @group methods (dobj) @result{} Methods for class java.lang.Double: boolean equals(java.lang.Object) java.lang.String toString(double) java.lang.String toString() @dots{} @end group @end example To call a method of an object the same structure indexing operator @samp{.} is used. Octave also provides a functional interface to calling the methods of an object through @code{javaMethod}. An example showing both styles is shown below. @example @group dobj = javaObject ("java.lang.Double", pi); dobj.equals (3) @result{} 0 javaMethod ("equals", dobj, pi) @result{} 1 @end group @end example @cindex method, invoking a method of a Java object @DOCSTRING(javaMethod) The following three functions are used to display and modify the class path used by the Java Virtual Machine. This is entirely separate from Octave's @env{PATH} variable and is used by the JVM to find the correct code to execute. @cindex classpath, displaying @cindex classpath, dynamic @cindex dynamic classpath @cindex classpath, static @cindex static classpath @DOCSTRING(javaclasspath) @findex javaaddpath @cindex classpath, adding new path @cindex path, adding to classpath @cindex classpath, dynamic @cindex dynamic classpath, adding new path @DOCSTRING(javaaddpath) @cindex classpath, removing path @cindex path, removing from classpath @DOCSTRING(javarmpath) The following functions provide information and control over the interface between Octave and the Java Virtual Machine. @DOCSTRING(javachk) @DOCSTRING(usejava) @cindex memory, displaying Java memory status @DOCSTRING(javamem) @DOCSTRING(java_matrix_autoconversion) @DOCSTRING(java_unsigned_autoconversion) @DOCSTRING(debug_java)