NAG Technical Report 3/2000

Calling the NAG C Library from Java


Start of report   Skip to Example 1   Skip to Example 3

4.2. Example 2

A linear equation solver, function f04arc

Here we show how to call a NAG C Library function which requires input/output array arguments: the function f04arc.

Contents

  1. Function prototype from the NAG C Library Manual
  2. Declaring the native function in our Java program
  3. Compiling the Java program
  4. Generating a header file for use by C
  5. Implementing the native function in C code
  6. Building the shareable library or DLL
  7. Running the program
  8. Quick summary of how to build the linear equation solver example

  1. Function prototype from the NAG C Library Manual
  2. According to the C Library Manual, the prototype for function f04arc looks like this:

      #include <nag.h>
      #include <nagf04.h>
    
      void f04arc(Integer n, double a[], Integer tda, double b[],
                  double x[], NagError *fail);
    
    The function is designed to solve the set of n linear equations A x = b, where A is an n by n matrix, and b and x are vectors of length n.

    Note that the argument tda is used to notify the NAG Library routine of the trailing dimension of the two-dimensional array A.

  3. Declaring the native function in our Java program
  4. As with Example 1, we will not attempt to pass the contents of the NagError structure back to Java. In our Java program, we will declare the function like this:

      // Declaration of the Native (C) function
      private native int f04arc(int n, double[] a, int tda, double[] b,
                                 double[] x);
    
    i.e. a method with return type int. Since we are not bothering to use the fail argument, we will use the int return value to send back any error code.

  5. Compiling the Java program
  6. Here is the complete source code of our Java program LinearEquations.java.
    public class LinearEquations
    {
    
      // Declaration of the Native (C) function
      private native int f04arc(int n, double[] a, int tda, double[] b,
                                 double[] x);
    
      static
        {
          // The runtime system executes a class's static
          // initializer when it loads the class.
          System.loadLibrary("nagCJavaInterface");
        }
    
      // The main program
      public static void main(String[] args)
        {
          double a[], b[], x[], r[], copyA[];
          int i, j, n, tda, retCode;
    
          // Create an object of class LinearEquations
          LinearEquations lineq = new LinearEquations();
    
          n = 3;
          tda = n;
    
          a = new double[n*n];
          b = new double[n];
          x = new double[n];
          r = new double[n];
          copyA = new double[n*n];
    
          a[0*n + 0] = 33.0;
          a[0*n + 1] = 16.0;
          a[0*n + 2] = 72.0;
          a[1*n + 0] = -24.0;
          a[1*n + 1] = -10.0;
          a[1*n + 2] = -57.0;
          a[2*n + 0] = -8.0;
          a[2*n + 1] = -4.0;
          a[2*n + 2] = -17.0;
    
          b[0] = -359.0;
          b[1] = 281.0;
          b[2] = 85.0;
    
          // Copy matrix A for later use (it gets overwritten by f04arc).
          for (i = 0; i < n * n; i++)
            copyA[i] = a[i];
    
          System.out.println();
          System.out.println("Call of NAG linear equation solver routine f04arc");
          System.out.println();
    
          // Print the input matrix A and vector b
          System.out.println("Input matrix A:");
          for (i = 0; i < n; i++)
            {
              for (j = 0; j < n; j++)
                System.out.print(" " + a[i*n + j]);
              System.out.println();
            }
          System.out.println();
    
          System.out.println("Input vector b:");
          for (i = 0; i < n; i++)
            System.out.println(" " + b[i]);
          System.out.println();
    
          // Call method f04arc of object lineq
          retCode = lineq.f04arc(n, a, tda, b, x);
    
          System.out.print("Return code from f04arc = ");
          System.out.println(retCode);
          System.out.println();
    
          if (retCode == 0)
            {
              // Print the solution vector x
              System.out.print("Solution vector x:\n");
              for (i = 0; i < n; i++)
                System.out.println(" " + x[i]);
              System.out.println();
    
              // Calculate and print residual vector
              for (i = 0; i < n; i++)
                {
                  r[i] = -b[i];
                  for (j = 0; j < n; j++)
                    r[i] += copyA[i*n + j] * x[j];
                }
              System.out.print("Residual vector r = A * x - b:\n");
              for (i = 0; i < n; i++)
                System.out.println(" " + r[i]);
              System.out.println();
            }
        }
    }
    
    Some points to note about this program:

    We can compile our Java program with the command

      % javac LinearEquations.java
    

  7. Generating a header file for use by C
  8. Having compiled LinearEquations.java, we can use javah to create a C header file:

      % javah -jni LinearEquations
    
    The generated header file, LinearEquations.h, contains this function prototype:
      JNIEXPORT jint JNICALL Java_LinearEquations_f04arc
        (JNIEnv *, jobject, jint, jdoubleArray, jint, jdoubleArray, jdoubleArray);
    

    As before, from the C point of view, our function has an extra two arguments: the Java environment pointer and the Java object. This time, we will need those arguments in our C code.

  9. Implementing the native function in C code
  10. Now that we have created the header file LinearEquations.h, we can write our C code implementation of Java_LinearEquations_f04arc. Here it is, in file LinearEquationsImp.c:

    #include <jni.h>      /* Java Native Interface headers */
    #include "LinearEquations.h"   /* Auto-generated header created by javah -jni */
    
    #include <nag.h>      /* NAG C Library headers */
    #include <nagf04.h>
    
    /* Our C definition of the function f04arc declared in LinearEquations.java */
    JNIEXPORT jint JNICALL Java_LinearEquations_f04arc
      (JNIEnv *env, jobject obj, jint n, jdoubleArray a, jint tda,
       jdoubleArray b, jdoubleArray x)
    {
      static NagError fail;
    
      /* First extract the arrays from Java */
      jdouble *apt, *bpt, *xpt;
      jsize len;
      int i;
    
      apt = (*env)->GetDoubleArrayElements(env, a, 0);
      bpt = (*env)->GetDoubleArrayElements(env, b, 0);
      xpt = (*env)->GetDoubleArrayElements(env, x, 0);
    
      /* Call f04arc */
      fail.print = FALSE;
      f04arc(n, apt, tda, bpt, xpt, &fail);
    
      /* Release the array elements back to Java */
      (*env)->ReleaseDoubleArrayElements(env, a, apt, 0);
      (*env)->ReleaseDoubleArrayElements(env, b, bpt, 0);
      (*env)->ReleaseDoubleArrayElements(env, x, xpt, 0);
    
      return fail.code;
    }
    
    Points to note:

  11. Building the shareable library or DLL
  12. This step is operating-system dependent.

    The compiler flags used were described in Section 7 of Example 1.

  13. Running the program
  14. Assuming that all has gone well, we can run the program using the command

      % java LinearEquations
    
    The expected output looks like this:

        Call of NAG linear equation solver routine f04arc
    
        Input matrix A:
         33.0 16.0 72.0
         -24.0 -10.0 -57.0
         -8.0 -4.0 -17.0
    
        Input vector b:
         -359.0
         281.0
         85.0
    
        Return code from f04arc = 0
    
        Solution vector x:
         1.0
         -2.0
         -5.0
    
        Residual vector r = A * x - b:
         0.0
         0.0
         0.0
    

    (If you get an error message saying that a library cannot be located, see the tip given in Example 1).

  15. Quick summary of how to build the linear equation solver example
  16. Given the two source files LinearEquations.java and LinearEquationsImp.c, issue the following commands:

Start of report   Skip to Example 1   Skip to Example 3
Copyright 2000 Numerical Algorithms Group
This page last modified Wednesday 10 May 2000 10:05:08
[NP3489]