Tutorial for Sparse Matrices
============================

Content
This tutorial shows how to use sparse matrices. It also demonstrates how to
include an existing application into NetSolve. The application to be used is
called NetSolve and provides a solver for large sparse linear systems. It was
developed at the University of Linz, Austria and you have to obtain a copy of
this software. But even if you don't have Pebbles you should be able after
reading through this tutorial to handle sparse matrices within NetSolve. The
tutorial includes the following steps:

  1. building and configuring the library
  2. installing the problem to the NetSolve repository
  3. testing the software from C and Matlab


Requirements
o on each server:
  o interface.cc - the wrapper function for Pebbles to NetSolve
  o outback.cc, extern.hh - a modification of Pebbles on how to pass options
  o pebbles.idl - a file which describes how the problem should be included
                  into the NetSolve repository (Interface Definition Language)
  o Pebbles - information about how to obtain Pebbles at
              http://www.numa.uni-linz.ac.at/Research/Projects/pebbles.html
o on the client:
  o test_pebbles.c - the client program which allows to perform a simple test



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

1. Building the Library
o at first install and compile Pebbles as described in the documentation, but:
  o copy the file outback.cc to your pebbles/libsrc/prepro directory and
  o replace the file pebbles/pebbles/extern.hh with the version provided here
  in the following it is assumed that Pebbles is installed in ~/pebbles, i.e.,
  the statically linked libraries after compiling Pebbles should be in
  ~/pebbles/lib/$MACHINE/
o build libpebbles.a within the Pebbles source tree
  $ cp interface.cc ~/pebbles/pebbles; cd ~/pebbles/pebbles
  $ c++ -c -fpic -o interface.o -I$HOME/pebbles/libsrc  \
    -DFORTRANDOUBLEUNDERSCORE -w interface.cc
  $ mkdir ~/pebbles/libpebbles
  $ cp ~/pebbles/libsrc/*/*.o ~/pebbles/libpebbles
  $ cp ~/pebbles/pebbles/interface.o ~/pebbles/libpebbles
  $ cd ~/pebbles/libpebbles; ar rc libpebbles.a *.o

  you should now have a file ~/pebbles/libpebbles/libpebbles.a

NOTES:
o Since Pebbles is writte in C++ and NetSolve in C we have to provide the
line 'extern "C" void pebbles(...)' at the beginning of interface.cc to make
sure that the internal nameing convention for the linker are fullfilled.

o NetSolve and Pebbles use the same storage convention for sparse matrices
(called the compressed sparse row format - CSR) which uses the 3 vectors:
  double *A - the values of the nonzero entries (length: nnz)
  int *col_index - the column index of each entry of the vector A (length: nnz)
  int *row_ptr - index to first nonzero entry at each row in col_index
                 (length: size+1 with row_ptr[size+1]=nnz)


2. Installing the Problem to the NetSolve Repository
Use idltopdf to convert pebbles.idl to pebbles.pdf and add the function to the
problems list in the file 'server_config'. Set NSPEBBLES_LIB to
$HOME/pebbles/libpebbles and recompile the server with the command
$ make server


3. Testing the Software from C and Matlab
The file test_pebbles.c demonstrates how to invoke the newly created function
pebbles via NetSolve. Compile it with with the following command:

$ gcc test_pebbles.c -o test_pebbles -I$NETSOLVE_ROOT/include -lnetsolve \
      -L$NETSOLVE_ROOT/lib/$NETSOLVE_ARCH

running ./test_pebbles should give the following output:

Initializing NetSolve...
Initializing NetSolve Complete
Sending Input to Server visitor1.cs.utk.edu
Downloading Output from Server visitor1.cs.utk.edu
+++ PEBBLES started
size: 4
nnz:  4
maxrowsize: 1
$$$ setup phase
$$$ solution phase
$$$ writting the solution
+++ PEBBLES finished
Solution:
--> 1.000000
--> 0.500000
--> 0.333333
--> 0.250000


In Matlab run the follwing commnds (assuming you have compiled the Matlab
libraries with "make matlab"):

>> addpath /path/to/NetSolve/bin/architecture
(e.g., /home/user/NetSolve/bin/i686_pc_linux_gnu)
>> x=netsolve('pebbles',A,b,x,'EPS_PCG=1e-6;SOLVE=1;ELEMENT_PRECOND=0');
(with A a positive definite sparse matrix, b the right hand side vector and x
the solution vector)



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