This is a sparse matrix toolkit for octave based
on the SuperLU package.

ID: $Id$

AUTHOR:  Andy Adler <adler@ncf.ca>

INSTRUCTIONS

0. Check that you have the following files:
  a Makefile
  b make_sparse.cc
  c make_sparse.h
  d sp_test.m
  e fem_test.m
  f superlu2.0patch.diff
  
0a. This is tested to work with octave-2.1.32
    It works with >2.1.30 if you apply the mkoctfile patch
    at www.octave.org/mailing-lists/octave-maintainers/2000/175

0b. If you already have a SuperLU subdirectory with
    SuperLU/SRC and SuperLU/CBLAS then ignore 
    steps 1-3

1. Download SuperLU from one of the following sites
                         http://www.netlib.org/scalapack/prototype
                         ftp://ftp.cs.berkeley/pub/src/lapack/SuperLU
                         http://www.nersc.gov/~xiaoye/SuperLU/

2. Unpack SuperLU into the directory you'll be building the
    octave sparse functions from

3. Apply the patch
          patch -p0 < superlu2.0patch.diff

4. Build the octave sparse functions
          make    in the octave sparse functions directory
          NOTE: do not run the SuperLU makefiles - 
               it doesn't build the right objects into the library

This makefile assumes that the SuperLU package has been unpacked
 in this directory. It compiles files directly from their locations
 in the SuperLU source. You do not need to use SuperLU makefiles.

SuperLU is available from http://www.netlib.org/scalapack/prototype
                          ftp://ftp.cs.berkeley/pub/src/lapack/SuperLU


AUTHOR:  Andy Adler <en254@ncf.ca>

COPYRIGHT:
Copyright (C) 1998-00 Andy Adler

   This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
   This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
   You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


SUPERLU COPYRIGHT:
The following copyright is taken from any of the
files in the SuperLU/SRC directory

/*
 * -- SuperLU routine (version 2.0) --
 * Univ. of California Berkeley, Xerox Palo Alto Research Center,
 * and Lawrence Berkeley National Lab.
 * November 15, 1997
 *
 */
/*
  Copyright (c) 1994 by Xerox Corporation.  All rights reserved.

  THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY
  EXPRESSED OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.

  Permission is hereby granted to use or copy this program for any
  purpose, provided the above notices are retained on all copies.
  Permission to modify the code and to distribute modified code is
  granted, provided the above notices are retained, and a notice that
  the code was modified is included with the above copyright notice.
*/ 

USAGE:
   sparse functions are provided for

   sparse -> create sparse matrices
   full   -> create full matrices from sparse
   splu   -> spare lu decomposition
   spfind -> find elements of sparse matrices
   nnz    -> number of non zero elements

   Unitary operators

   S'    S.'   -S    ~S

   Binary operators
   ==  +   -   *   .*   \ 

   Selection
   A( fortran_vec ) ,   A( idx1, idx2 )


MISSING FEATURES (TODO FILE)
(This is more or less in the order of importance, and
 probability of accomplishment)

1.  Sparse solution: there is no code for
    sparse(index1,index2) = submatrix
    [ sparse , sparse ]

2.  More efficient code for:
    sparse \ sparse
    spinv
    splu

3.  More "sophisticated" matrix operations on sparse
    eigenvectors
    chol
    SVD
    etc.

KNOWN AND PREDICTED BUGS AND FEATURES:

1.  It probably leaks memory. I'll try to test this more carefully
    after I stop adding features.

2.  It does not support empty matrices properly.
    It does not support completely sparse (all zero) matricies either.

3.  The attempt here is to provide compatability to the main MATLAB
    sparse matrix entry points. The SuperLU provides slightly different
    fuctionality to MATLAB, and, therefore this toolkit provides
    different features.

    For example, the column permutation algorithm (and approach) is
    different.

    Additionally, I don't intend to provide replacements for the
    MATLAB sparse functions I consider frills. eg sprand.m, treeplot.m

4.  SuperLU uses the int data type as indices. Since ints are normally
    4 bytes (at least on i386 machines), this is not a great problem.
    There may be still a few places where an int is used to refer
    to i+j*m, which means that sparse operations on matrices where
    m*n > maxint/2 may be buggy. I've tried to fix this, but there
    may be some left.  Email me if you find any.

5.  Sparse solve is a little faster than the MATLAB equivalent, except
    it seems not to choose the factoring as well. Using a perm_c spec of
    2 for symetric matrices will get speed improvements of ~ 1.5.
    (For the FEM problems I use it for)

TODO:

add complex test cases 

add tests for failures (matrix size mismatch)

go though sparse_ops.h and support all zero matrices

test code for all zero and empty matrices

more efficient code for sparse \ sparse
  - fix casting spagetti

support sparse \ sparse for complex

move code to c++ operators - so we can use sparse from liboctave

fix error for sparse(1)\1
   DEBUG:sparse - matrix_to_sparse
   DEBUG:sparse( SuperMatrix A)
   DEBUG:sparse - numeric_conversion_function
   DEBUG:sparse - default_numeric_conversion_function
   DEBUG:sparse - matrix_value
   DEBUG:sparse - sparse_to_full
   error: operator \: nonconformant arguments (op1 is 1x1, op2 is 1x1)

   #include <octave/oct.h>
   defun_dld (jnk, args, , "jnk" ) {
     matrix x(1,1); x(0,0)= 1; octave_value o1(x);
     octave_value o2(2.0);
     octave_value_list retval; retval(0)= o1/(o2);
     return retval;
   }

complex sparse constructor will create real sparse if matrix
is actually real

make debug constructor which sanity checks matrices
 - option which checks if no nonzero elems isist

complex sparse functions for splu - spinv