Calling NAG Library Routines from Octave - Example 5

NAG Technical Report 3/2009

Calling NAG Library Routines from Octave


Start of report   Skip to Example 1   Skip to Example 2   Skip to Example 3   Skip to Example 4

3.5. Example 5

tsa

Univariate time series, seasonal and non-seasonal differencing - G13AAF routine

We show how to call a routine from the NAG Fortran Library: G13AAF. Although we are calling a NAG Fortran Library routine, we must use C code for the glue between Octave and NAG.

Contents

  1. Function prototype from the NAG Fortran Library Manual
  2. C++ function
  3. Compiling into Oct-File
  4. Calling the function
  1. Function prototype from the NAG Fortran Library Manual

    According to the Fortran Library Manual, the prototype for function G13AAF looks like this:

          SUBROUTINE G13AAF(X, NX, ND, NDS, NS, XD, NXD, IFAIL)
          INTEGER           NX, ND, NDS, NS, NXD, IFAIL
          DOUBLE PRECISION  X(NX), XD(NX)
    

    X, NX, ND, NDS and NS are all input arguments, XD and NXD are output arguments and IFAIL is the error handling argument. See the NAG FORTRAN Library Manual [7] for detailed argument descriptions.

  2. C++ function

    Here is the source code of our C++ function nag_tsa.cc:

    #include <octave/oct.h>
    #define Complex NagComplex
    #define MatrixType NagMatrixType
    #include <nagmk22.h>
    
    DEFUN_DLD (nag_tsa, args, ,
      "Calls G13AAF, which carries out non-seasonal \n\
    and seasonal differencing on a time series.\n")
    {
      // Variable to store function output values
      octave_value_list retval;
      // Retrieve input arguments from args
      NDArray x = args(0).array_value();
      Integer nx = args(1).int_value();
      Integer nd = args(2).int_value();
      Integer nds = args(3).int_value();
      Integer ns = args(4).int_value();
      // Declare local variables
      Integer nxd, ifail;
      dim_vector dv(1); dv(0)=nx;
      NDArray xd(dv);
    
      // Call NAG routine
      ifail = -1;
      g13aaf_(x.fortran_vec(),nx,nd,nds,ns,xd.fortran_vec(),nxd,ifail);
    
      // Assign output arguments to retval
      retval(0) = xd;
      retval(1) = nxd;
      retval(2) = ifail;
    
      return retval;
    }
    

    Points to note about this code:

    • For clarity, the input arguments type checking and error message printing have been omitted in the article text. However, they have been added to the file you can download from this site.
    • Complex and MatrixType types are defined in Octave and NAG header files. We are not using these types in this example, so we can simply rename one of their definitions.
    • The third DEFUN_DLD argument (nargout) is not used, so it is omitted in order to avoid the warning from gcc about an unused function parameter.
    • We need to add an underscore to the name of Fortran routine called from C/C++, so G13AAF became g13aaf_
    • All arguments are passed as pointers to a variable, but the C Header file adds &'s to the arguments that need them, so we omit them in the call.
  3. Compiling into Oct-File

    To compile the C++ function into oct-files, we use the mkoctfile script supplied with Octave:

      % mkoctfile nag_tsa.cc -L/opt/NAG/fll6a22df/lib -lnag_nag -I/include
    

    where:

    • the -L switch tells the C compiler where to look for NAG FORTRAN Library installed on your system;
    • -lnag_nag is the name of the NAG FORTRAN Library;
    • the -I switch should be followed by the location of NAG header files.
  4. Calling the function

    Assuming that all has gone well, we can call the function as if it was part of Octave itself, i.e. either from the Octave command line or from within an Octave program. An example call may be:

    octave:1> x=[120.0 108.0  98.0 118.0 135.0 131.0 118.0 125.0 121.0 100.0 82.0  82.0  89.0  88.0  86.0 96.0 108.0 110.0  99.0 105.0];
    octave:2> [xd,nxd,ifail]=nag_tsa(x,20,2,1,4)
    xd =
    
       -11
       -10
        -8
         4
        12
        -2
        18
         9
        -4
        -6
        -5
        -2
       -12
         5
         2
       -10
       -13
        17
         6
       105
    
    nxd =  14
    ifail = 0
    

    Tip: If you get an error message in Octave saying that libnag_nag.so cannot be found, you may need to set an environment variable to tell the system where to look. The environment variable name is operating-system dependent. On Linux machines it is named LD_LIBRARY_PATH, and is a colon-separated list of directories to be searched for libnag_nag.so. For example, if you use the C shell, the command

      % setenv LD_LIBRARY_PATH /opt/NAG/fll6a22df/lib:${LD_LIBRARY_PATH}
    

    will ensure that directory /opt/NAG/fll6a22df/lib gets searched.


Start of report   Skip to Example 1   Skip to Example 2   Skip to Example 3   Skip to Example 4