--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/main/sparse/README	Wed Oct 10 19:54:49 2001 +0000
@@ -0,0 +1,202 @@
+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