jPETScTao

What it is

jPETScTao is the name for a Java project, that tries to make a part of the functionality of two numeric libraries PETSc and TAO accessible for Java programs. It utilizes the JNI to achieve that.
What it can

At the moment it is possible
  • to use TAO to solve unconstrained optimization problems, using PETSc for the linear algebra
  • to use PETSc SNES to solve nonlinear equations.
  • to use PETSc KSP to solve linear equations.
  • as a very experimental feature:
    to let it spawn some slave JavaVMs and use MPI to use the parallel skills of PETSc to do the calculations in parallel on one SMP machine.

What it can't

  • it is not thread save, because PETSc isn't. so you must not run it simultaneous in one JavaVM or you endanger the stability of the hole VM. That's why it can span slave JavaVMs to do parallel calculations.
  • at the actual state it makes only a small fraction of the functionality of the very feature rich PETSc accessible.

How to use

It's similar to PETSc and TAO

The names of the classes (= structures in c) and methods are the same (only adapted to Java naming conventions) and especially the functionality of the methods are at least hoped to be the same. Functions that belong logically to some structure (e.g. Vec or Mat) in both libraries carry the structure Name as Prefix (e.g. MatGetSize). That prefix is stripped off for those functions, that become members of the corresponding class the same time.

Some further differences are necessary

Because of the different natures of c and java mainly two big changes to the API were necessary:
  • The exception handling in PETSc is realized with a PetscErrorCode as return value for every function. This is translated to java exception handling. So every method can throw a PETScError, which is a child of java.lang.Error (=> you don't have to catch it) and return something else.
  • As the return value is used on the c side for exceptions, the only available ways back to the caller are reference or pointer arguments. Additionally in both of the libraries it is quite common to use multiple parameters of methods as "return values". This problem is solved on the java side by packing multiple return values to one returned object of an individual class for each concerned function. If the function has only one "return value" it is just returned. (thanks to the java exception handling that is possible in contrast to the c side situation)
  • For some functions that get arrays by passing its pointer and size as two parameters are translated to get only one array parameter. Because the correspondence between an array's pointer and its size is not found automatically this is not done for all functions. If not it is important to pass the right size besides the array. Otherwise the VM could crash.
To give an example for these change let's look at the following c prototype:

	PetscErrorCode MatGetSize(Mat mat,PetscInt *m,PetscInt* n);
		
it is translated to java to the following Mat class's members:

	public static class GetSizeResult {
		public final int m;
		public final int n;
	}

	public native GetSizeResult getSize();
		
A small example

This simple example uses jPETScTao to find and calculate the minimum of:
f: R->R , x|-> x^2
as highlighted html file
as plain Java file
A small MPI example

as highlighted html file
as plain Java file
download

You can download the complete source code : jPETScTao-src.jar.
For binary versions look at the jrworkspace project. It's integrated as the library called jPETScTao.
api-doc

javadoc output