Tutorial for Matrix and Vector Operations
=========================================

Content
This tutorial shows how to use matrices and vectors within NetSolve by
developing a little programm which either invokes a custom function to
perform the multiplication or uses the BLAS routine dgemm. This includes
the following steps:

  1. building the library
  2. installing the problem and adding BLAS to the NetSolve repository
  3. invoking the function via NetSolve


Requirements
o the following files are needed (they should be in the current directory)
  o libmatmul.c - contains the function which should perform the calculation
  o matmul.idl - a file which describes how the problem should be included
               into the NetSolve repository
  o myprog.c - an example program which invokes the NetSolve function



Instructions
------------

1. Building the Library
NetSolve provides all functions through statically linked libraries. Execute the
following steps on the server to build libmatmul.a

$ gcc -c libmatmul.c
$ ar rc libmatmul.a libmatmul.o


2. Installing the Problem and Adding BLAS to the NetSolve Repository
To invoke a new function from the NetSolve client you have to add the function
to the problems list in a NetSolve server and recompile the server. Perform the
following steps to include 'matmul'

o create a problem description file with
  $ $NETSOLVE_ROOT/bin/$NETSOLVE_ARCH/idltopdf matmul.idl
  which generates the file matmul.pdf

o copy the file matmul.pdf to the problems subdirectory in your NetSolve directory

o edit the file "server_config" in your NetSolve directory and add the following
  line in the "@PROBLEMS:" section:
  ./problems/matmul.pdf

o to rebuild the server, you have to set an environment variable which points to
  the directory of the previously created library (required by the problems
  definition file); depending on you shell execute
  $ export NSMATMUL_LIB=/path/to/libmatmul
  or
  $ setenv NSMATMUL_LIB /path/to/libmatmul

o afterwards rebuild the server with the command
  $ make server
  in your NetSolve directory

To include the function 'dgemm' provided by the BLAS package
(http://netlib.org/blas) you only have to uncomment the line
"#./problems/blas_subset" in the file 'server_config'. NetSolve provides a
subset of the BLAS package in the NetSolve directory
./src/SampleNumericalSoftware/BLAS.

Hint: NetSolve also provides a subset of LaPack. If you want to include the
complete LaPack uncomment "#./problems/lapack" in 'server_config' and rerun
configure with the following additional options
"--with-blaslib=/path/to/libblas.a --with-lapack-lib=/path/to/liblapack.a".

Note: All these steps have to be performed at the machine where your server is
running. Also make sure to kill the server if it is currently running.


3. Invoking the Function Via NetSolve
The file myprog.c demonstrates how to invoke the function calc via NetSolve in
C. When you compile it you have to provide the include and library directory of
NetSolve. If you have set the NETSOLVE_ROOT environment variable to your
NetSolve directory and running this tutorial on x86 under Linux the command
would be:

$ gcc myprog.c -o myprog -I$NETSOLVE_ROOT/include -lnetsolve \
      -L$NETSOLVE_ROOT/lib/i686_pc_linux_gnu

Invoking myprog uses 3 arguments:
o matrix size: integer with the dimension of the used matrix
o mode: 1 - blocking call
        2 - non-blocking call
        3 - task-farming
o routine: 1 - custom function matmul in libmatmul.c
           2 - dgemm from the BLAS package

Note: Be sure to have an agent and your newly compiled server running. Also
check that the NETSOLVE_AGENT enironment variable is set on your client (it
should be the same value as the "@AGENT:" line in server_config in the NetSolve
directory).


Last modified: March 19th, 2003
Christoph L. Fabianek, fabianek@cs.utk.edu
