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

ID: $Id: README,v 1.2 2001/10/12 02:24:28 aadler Exp $

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. Make sure that your version of octave is compiled
    with:
    ./configure --enable-dl --enable-shared
  
0b. This is tested to work with octave-2.1.34
    It works with >2.1.30 if you apply the mkoctfile patch
    at www.octave.org/mailing-lists/octave-maintainers/2000/175

0c. If you already have a SuperLU subdirectory with
    SuperLU/SRC and SuperLU/CBLAS then ignore 
    steps 1-3
    (You will have SuperLU if you downloaded this from
     sourceforge.net)

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

5. Installation:
   Copy 1) make_sparse.oct and 2) the links to make_sparse.oct
   into any directory in your LOADPATH
         full.oct -> make_sparse.oct
         nnz.oct -> make_sparse.oct
         sparse.oct -> make_sparse.oct
         spfind.oct -> make_sparse.oct
         spinv.oct -> make_sparse.oct
         splu.oct -> make_sparse.oct


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: GPL + opensource linking
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.

   In addition to the terms of the GPL, you are permitted to link
this program with any Open Source program, as defined by the
Open Source Initiative (www.opensource.org)


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.  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

2.  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.

3.  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 - done

add tests for failures (matrix size mismatch) - done

go though sparse_ops.h and support all zero matrices - done

test code for all zero and empty matrices - all zero done

complex sparse select operations

more efficient code for sparse \ sparse
  - fix casting spagetti

support sparse \ sparse for complex - done

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;
>   }
--> fixed in octave-2.1.34

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  - done

sp_inverse_uppertriang segfaults for spinv(sparse(ones(3))). It should warn
