An Introduction to javaoctave for the User

Historically, there was an octave package which allowed the converse: using java from within octave. In the meantime, i.e. with version at least 4.3.0+, octave this piece of software had been included in the base version of octave. In the long run, the maintainer of javaoctave intends to include this software into octave either. Then octave can be invoked from within java and vice versa. As matlab offers both and octave is supposed to clone matlab, it would be strictly speaking necessary, to include a bridge like javaoctave into octave.

Still history is not so far. The original versions javaoctave were written by Kim Hansen at Ange Optimization ApS for the KENAI project. After the KENAI site disappeared, the current maintainer of javaoctave decided to go on with that task since he needs that software himself. So far there is no explicit bug tracker but you can email me via <reissner@simuline.eu> if something is wrong or you miss a feature. After this project has reached some maturity, the current maintainer is going to pass all software to octave.

Chapter 2. First Steps

Here, it is described how javaoctave is used. The prerequisites are

java jdk at least version 6, where tests are with java 11.

octave version >3.5, where tests are with octave 5.2.0.

this software, javaoctave, is registered at sonatype the repositories given by the distribution-management, thus containing among other things the relevant jar files for all versions. To be more precise, these are in .../eu/simuline/octave/javaoctave. For some reason, in sonatype, only the snapshot directory works. Using javaoctave in a maven build, the dependency to javaoctave is given by its maven coordinates.

When using javaoctave, it is helpful to consult this manual for the big picture and the api-docs for details. The core class of javaoctave is OctaveEngine which wraps an octave instance. But to create such an engine, an OctaveEngineFactory is needed. It is created using a default constructor and can be customized with setter methods before creating an OctaveEngine. The values set determine the parameters of the OctaveEngine created.

Example 2.1. OctaveEngine with default options

A minimal example to create an OctaveEngine is the following:

import eu.simuline.octave.OctaveEngineFactory;
import eu.simuline.octave.OctaveEngine;
... 
OctaveEngineFactory oef = new OctaveEngineFactory();
OctaveEngine oe = oef.getScriptEngine();

Here, the octave-engine is created with default parameters defined in the factory.

Example 2.2. OctaveEngine with custom options

Before an engine is created, the parameters of the factory can be modified, which causes the factory to create an octave-engine with according parameters.

import eu.simuline.octave.OctaveEngineFactory;
import eu.simuline.octave.OctaveEngine;
... 
OctaveEngineFactory oef = new OctaveEngineFactory();
oef.setArgsArray(new String[] {"--silent", "--no-init-file"})
OctaveEngine oe = oef.getScriptEngine();

Command line options are described both form octave perspective and from javaoctave perspective. CAUTION: OctaveEngineFactory has default arguments which are suited to invocation from as a script engine and not all options allowed by octave are usable in the context Besides command line options, one may set the octave executable, either by an executable file, by a system property or by a command. The latter is the active by default with default value octave. Together with the command line arguments described below, this defines the invocation of the underying octave engine. In addition, it is possible to define the environment and the working directory, both by default inherited from the invoking process. Also the encoding of the input, output and error stream of the octave process can be configured. The octave process is connected via an input writer and a reader for output and error, respectively. Whereas the output writer is not configurable, for the input a writer for logging may be configured (default none), and and also error output may be configured (by default tied to System.err). Finally, it is possible for to define a threadpool for accessing octave: By default it is a fixed thread pool with 2 threads, but one may also configure the number or define a cached thread pool.

Example 2.3. OctaveEngine with a combination of custom options

Of course all the kinds of parameters of a factory may be combined. To that end, the setter methods return the original factory to allow stacking.

import eu.simuline.octave.OctaveEngineFactory;
import eu.simuline.octave.OctaveEngine;
... 
OctaveEngineFactory oef = new OctaveEngineFactory();
oef.setArgsArray(new String[] {"--silent", "--no-init-file"})
   .setEnvironment(new String[] {"JAVA_ROOT=/usr/lib64/jvm/java", 
                                 "LANG=en_US.UTF-8"});
OctaveEngine oe = oef.getScriptEngine();

import eu.simuline.octave.OctaveEngineFactory;
import eu.simuline.octave.OctaveEngine;
... 
OctaveEngine oe = new OctaveEngineFactory()
   .setArgsArray(new String[] {"--silent", "--no-init-file"})
   .setEnvironment(new String[] {"JAVA_ROOT=/usr/lib64/jvm/java", 
                                 "LANG=en_US.UTF-8"})
   .getScriptEngine();

After having created an octave-(script-)engine, this can be used to evaluate scripts in the matlab language. For a complete reference of available methods, consult the apidocs; what we want to provide here is an overview. The core method is void eval(String script) which allows to execute some valid matlab code, or say script. Essentially, this is all a user needs. Nevertheless, it is both cumbersome to pass a java object to octave and to read back an octave object into java. Thus there are special methods

void put(String key, OctaveObject value) to pass a java object representing an octave type to an octave variable
and <T extends OctaveObject> T get(final Class<T> castClass, final String key) to get back from an octave variable an octave object represented by a java object with according type.

Typically, evaluations are preceeded by put-commands and succeeded by get-commands.

Example 2.4. Basic Use Case

A simple example for a cycle consisting of passing data from java to octave, performing a computation and passing back the result is the following:

oe.put("dIn", Octave.scalar(42.0));
oe.eval("dOut=sin(dIn);");
OctaveDouble od = oe.get(OctaveDouble.class, "dOut");
double jd = od.get(1,1);

Of course, oe is an octave engine created as described in the above examples. First, Octave.scalar(42.0) converts the java double 42.0 into an OctaveDouble, which is still a java class in javaoctave package eu.simuline.type but corresponds with an octave type which allows put to assign that value to octave variable dIn. Then oe.eval("dOut=sin(dIn);"); evaluates the sine and passes the result to octave variable dOut. Finally, OctaveDouble od = oe.get(OctaveDouble.class, "dOut"); pushes the value dOut back to java and to get back a double just use the getter method as shown above.

The last thing to do within a javaoctave session is releasing the resources normally via oe.close() and in exceptional cases via oe.destroy().

Chapter 3. Meta-Info

We inserted this section here although it would fit better later to avoid that it is ignored. Metainfo is not functional but still important. The class OctaveEngine provides several methods on versions:

getOctaveVersion() returns the version string of the underlying octave.
getOctaveInJavaVersion() in contrast, returns the version string for javaoctave
isOctaveVersionAllowed() much more important returns whether those versions fit together.

It seems to be vital to ensure that versions fit together. If not, there is a risk that silently something goes wrong.

Chapter 4. Putting and Getting Values

Table of Contents

Basic Java Types: Scalars and Matrices

The utility class Octave

Complex Types

Special Matrix Types

Types not yet described

Types that shall/may not be implemented

Unsigned Integer Types

Extending this Software to further types

In general, for getting and setting (to be more precise putting) values, the package eu.simuline.octave.type is needed, comprising java classes corresponding with octave types like OctaveDouble and the utility class Octave. Except Octave, the class names have the form OctaveXXX, where XXX indicates the octave type or a java type corresponding with that octave type.

The relation between the java types in eu.simuline.octave.type and the corresponding octave types is given in eu.simuline.octave.io.impl. This site also informs on the progress of implementation of the various types. All required information can be found in the api-docs. For a deeper understanding see the implmentation documentation implmentation documentation.

The following sections treat various categories of octave types and, if existent, introduce the corresponding java types in package eu.simuline.octave.type. We now give a short introduction to each of it.

Table 4.1. TOT: Table of types

index	octave type	`eu.simuline.octave.type`	section
1	unknown class	---	the section called “Types that shall/may not be implemented”
2	cell	OctaveCell	the section called “Types not yet described”
3	(double) scalar	OctaveDouble	the section called “Basic Java Types: Scalars and Matrices”
4	complex (double) scalar	OctaveComplex	the section called “Complex Types”
5	(double) matrix	OctaveDouble	the section called “Basic Java Types: Scalars and Matrices”
6	(double) diagonal matrix	---	the section called “Special Matrix Types”
7	complex (double) matrix	OctaveComplex	the section called “Complex Types”
8	complex (double) diagonal matrix	---	the section called “Special Matrix Types”
9	range	(OctaveFake)	the section called “Types not yet described”
10	bool (scalar)	OctaveBoolean	the section called “Basic Java Types: Scalars and Matrices”
11	bool matrix	OctaveBoolean	the section called “Basic Java Types: Scalars and Matrices”
12	string	OctaveString	the section called “Types not yet described”
13	sq_string	OctaveString	the section called “Types not yet described”
14	int8 scalar	---	the section called “Basic Java Types: Scalars and Matrices”
15	int16 scalar	---	the section called “Basic Java Types: Scalars and Matrices”
16	int32 scalar	OctaveInt	the section called “Basic Java Types: Scalars and Matrices”
17	int64 scalar	OctaveLong	the section called “Basic Java Types: Scalars and Matrices”
18	uint8 scalar	---	the section called “Types that shall/may not be implemented”
19	uint16 scalar	---	the section called “Types that shall/may not be implemented”
20	uint32 scalar	---	the section called “Types that shall/may not be implemented”
21	uint64 scalar	---	the section called “Types that shall/may not be implemented”
22	int8 matrix	---	the section called “Basic Java Types: Scalars and Matrices”
23	int16 matrix	---	the section called “Basic Java Types: Scalars and Matrices”
24	int32 matrix	OctaveInt	the section called “Basic Java Types: Scalars and Matrices”
25	int64 matrix	OctaveLong	the section called “Basic Java Types: Scalars and Matrices”
26	uint8 matrix	---	the section called “Types that shall/may not be implemented”
27	uint16 matrix	---	the section called “Types that shall/may not be implemented”
28	uint32 matrix	---	the section called “Types that shall/may not be implemented”
29	uint64 matrix	---	the section called “Types that shall/may not be implemented”
30	sparse bool matrix	OctaveSparseBoolean	the section called “Special Matrix Types”
31	sparse (double) matrix	---	the section called “Special Matrix Types”
32	sparse complex (double) matrix	---	the section called “Special Matrix Types”
33	struct	OctaveStruct	the section called “Types not yet described”
34	scalar struct	OctaveStruct	the section called “Types not yet described”
35	class	---	the section called “Types that shall/may not be implemented”
36	cs-list	---	the section called “Types that shall/may not be implemented”
37	magic colon	---	the section called “Types that shall/may not be implemented”
38	built-in function	---	the section called “Types that shall/may not be implemented”
39	user defined function	---	the section called “Types not yet described”
40	dynamically linked function	---	the section called “Types not yet described”
41	function handle	---	the section called “Types not yet described”
42	inline function	---	the section called “Types not yet described”
43	float scalar	---	the section called “Types not yet described”
44	float complex scalar	---	the section called “Types not yet described”
45	float matrix	---	the section called “Types not yet described”
46	float diagonal matrix	---	the section called “Types not yet described”
47	float complex matrix	---	the section called “Types not yet described”
48	float complex diagonal matrix	---	the section called “Types not yet described”
49	permuatation matrix	---	the section called “Types not yet described”
50	null_matrix	---	the section called “Types not yet described”
51	null_string	---	the section called “Types not yet described”
52	null_sq_string	---	the section called “Types not yet described”
53	lazy_index	---	the section called “Types not yet described”
54	onCleanup	---	the section called “Types not yet described”
55	octave_java	---	the section called “Types not yet described”
56	object	---	the section called “Types not yet described”

The octave types listed in Table 4.1, “TOT: Table of types” are given by the octave command typeinfo which returns a one dimensional cell array of strings with indices given in the first row. The second row is the name of the octave class. The third column shows the corresponding java type, if any and the last column gives a reference for further information.

Since octave is numeric software, octave's 'numerological' types, i.e. numerical types and the logical types are most important. A subset of these has a counterpart in java, and these are the types we start with in the section called “Basic Java Types: Scalars and Matrices”.

Basic Java Types: Scalars and Matrices

Most basic java types are numerological:

the boolean type boolean corresponding with the octave type bool ,
the signed integer types byte, short, int and long corresponding with the octave types int8, int16, int32 and int64, respectively, and
the floating point types float and double corresponding with the octave types float and double, respectively.

One difference between java and octave is, that the octave types may be matrices in any dimension indcluding scalars as special case, whereas the java types are scalars only. Thus the octave types must be declared as scalar or matrix. So the complete type is e.g. float scalar or float matrix. Since double is the type which is most frequently used, double scalar is written as scalar and double matrix is written as matrix. Likewise, bool scalar is written as bool.

Also in java integer types are always signed, whereas octave offers for each siged type an according unsigned type.

It would be a good design decision for the types in package eu.simuline.octave.type to provide for each octave type an according java type. On the other hand, scalars may be held in 1x1 matrices and so the types in eu.simuline.octave.type need not necessarily contain scalar types. The current implementation of javaoctave uses matrix types to hold scalar objects also. So getting octave scalars results in java matrices and putting a matrix results in a scalar if the matrix is 1x1.

Thus the class names OctaveXXX do not contain neither Scalar nor Matrix. Instead, XXX is just the java type corresponding with the according octave type.

The utility class `Octave`

As described in the section called “Basic Java Types: Scalars and Matrices” all basic types including scalar (doube) and (scalar) bool can be exchanged between octave and java. Nevertheless, putting values of these types requires invocation of a quite complex constructor because there is no explicit scalar type but only a matrix type which also represents scalars as 1x1 matrices. Thus we habe to invoke new OctaveDouble(new double[] {d}, 1, 1) to create an octave double with value d. For convenience we use method Octave.scalar(double d) instead.

Likewise this is true for the type (scalar) bool but here is the additional aspect, that it is not desirable to create more instances of scalars representing nothing but true or false. Method Octave.bool(boolean) creates octave booleans conveniently without creating superfluous instances.