NAG Technical Report 5/2009

Calling NAG Library Routines from Scilab

3.1. Example 1

Dawson's Integral F(x) (s15afc)

Here we show how to write an interface to a NAG C Library function with only one return value: Dawson's integral (s15afc).

Contents

1. Function prototype from the NAG C Library Manual
2. C Interface
3. Compiling with the builder script
4. Example of calling the function

1. Function prototype from the NAG C Library Manual

   According to the C Library Manual, the prototype for function s15afc looks like this:

       #include <nag.h>
       #include <nags.h>
   
       double s15afc(double x)
   

   This function takes one input variable of type double and returns the evaluation of Dawson's integral from zero up to the input value x.

2. C Interface

   Here is the source code of our interface written in C nag_intext1.c:

        /* Example 1
           =========
   
          Shows how to interface a simple NAG routine with Scilab.*/
   
        #include "stack-c.h"
        #include <nag.h>
        #include <nags.h>
   
        int nag_intext1(char *fname)
        {
        // y = nag_dawson(x)
        int m1,n1,l1;
        int m2,n2,l2;
        double x, y;
        int minlhs=1, minrhs=1, maxlhs=1, maxrhs=1;
        Nbvars = 0;
        
        // Check that we have the right number of input and outputs
        CheckRhs(minrhs, maxrhs);
        CheckLhs(minlhs,maxlhs);
   
        // m1, n1 and l1 are outputs of GetRhsVar.  m1, and n1
        // are the size of the input matrix, and l1 points 
        // to where the first element of the matrix is stored 
        // on the stack.
        //
        // Get the first (1) double precision "d" variable of 
        // size 1x1
        GetRhsVar(1, "d", &m1, &n1, &l1);
   
        if (m1!=1 || n1!=1)
        {
        sciprint("%s: Dimension of input 1 should be 1x1\r\n",fname);
        Error(999); return(0);
        }
   
        // CreateVar only gives the output l2, which points to
        // the first element of the space given to the matrix
        // of size m1 by n1
        //
        // Create the second (2) double precision "d" variable 
        // of size 1x1
        CreateVar(2, "d", &m1, &n1, &l2);
   
        // Get the input of the Scilab function from the stack
        // which is stored at variable 1
        x = *stk(l1);
   
        // Execute s15afc
        y = nag_dawson(x);
   
        // Put the solution y onto the stack in variable 2
        *stk(l2) = y;
   
        // Point the first output of the Scilab function to the 
        // solution y stored in variable 2
        LhsVar(1) = 2;
   
        return(0);
        }
   

   Points to note about this code:

   • The interface doesn't take in the input arguments of the function as its arguments, but only takes fname the name of the function in Scilab. In this example we have chosen fname to be the same as the NAG C library name.
   • The Scilab function GetRhsVar is used to retrieve the input arguments of fname
   • CreateVar creates a variable into which the NAG output is placed
   • The interface doesn't actually return the outputs of the function fname - instead the Scilab array LhsVar stores the variable numbers that are stored on Scilab's double precision stack stk()

3. Compiling with the Builder Script

   To compile and link this function, you can run the build script nag_builder1.sce which links this interface to the function name fname that will be seen in Scilab. This must be run in the same directory as the interface file, and when run successfully, generates a loader script loader.sce that needs to be executed in order to dynamically link the newly created library into Scilab.

       exec nag_builder1.sce
       exec loader.sce
   

4. Calling the function

   If the function built and the loader.sce file loaded the function without problem, then we can use the function within Scilab, either on the command-line or in a script. Here we run the example script, nag_example1.sce.

       --> exec nag_example1.sce
       y  =  - 0.3013404
   

   Tip: If you get any error messages in Scilab check the troubleshooting section.