Created Wed Dec 3 13:56:13 EST 2003 (pletzer@pppl.gov, transp_support@pppl.gov) $Id: README,v 1.12 2004/02/11 13:27:16 pletzer Exp $ SupraLU ======= A library to solve (8-byte) real and (16-byte) general complex sparse matrix problems in C, Fortran90 and Python. ABSTRACT SupraLU is a thin layer on top of the sequential SuperLU library (http://crd.lbl .gov/~xiaoye/SuperLU/). The core of SupraLU is written in C with hooks written in Fortran90 and Python. SupraLU can be used to: * solve unsymmetric linear systems (using the SuperLU engine) * compute the determinant * compute eigenvalues/eigenvectors (only for the complex version and based on an inverse iteration scheme) * perform basic linear algebra operations (matrix dot vector multiplications) The underlying SuperLU data structure uses a zero-based compressed column storage (CCS) format for the spars matrix representation. See for instance http://www.netlib.org/linalg/html_templates/node92.html for a description of the CCS format. The SuperLU structure is manipulated via API calls whose first argument take an opaque handle (http://w3.pppl.gov/~pletzer/programs/fortran-c-c++/opaque_handles.html). The handle contains the address of the underlying C data structure, it can be freely passed back and forth between C and Fortran /Python. The handle gives an object oriented flavor to SupraLU allowing several instances to co-exist. The numerical method used to solve systems is based on the LU decomposition. While there are iterative methods that are faster for large matrices, particularly Hermitian ones, the SuperLU engine has been found to be very robust. KEYWORDS Real and complex sparse matrices, eigenvectors, eigenvalues, determinant, LU decomposition. PRECISION Double and double complex. PORTABILITY SupraLU was tested and developed on Linux-intel. PREREQUISITES * SuperLU: http://crd.lbl.gov/~xiaoye/SuperLU (version 3.0) * a tuned version of Blas (optionally) * gmake * Python (for the documentation system and in order to use the Python interface) The Fortran interface requires * NetCDF: http://www.unidata.ucar.edu/packages/netcdf/ * Ezcdf: (included) the latter in order to save to and load from disk. INSTALLATION C and Fortran interfaces see included file INSTALL{_SupraLu}. The Python interface: As root type python setup.py --superlu-prefix= install [--prefix=] If you don't have root access, type python setup.py --superlu-prefix= --blas-prefix= build This will create the shared objects {z,d}supralu.so under build/ ("d" for double and "z" for double complex). You will need to point the PYTHONPATH variable to build/. You will also need to add the locations of the blas and Superlu libraries to your LD_LIBRARY_PATH. TESTING THE SOFTWARE To test the library, type cd /test ./supralu_test To test the Python interface, type python tester.py DOCUMENTATION The C API documentation is under CAPI_html/. The Fortran documentation is under FAPI_txt/. The Python documentation is under PyAPI_html/. How the interfaces differ: The low level interface is written in C and is directly callable from Fortran. The Fortran module supra_mod.f90 implements methods, in particular, to construct a sparse matrix, to solve a linear system, and to compute the determinant. A sparse matrix derived type is defined in superlu_mod.f90, which comes in two flavors sparseC16_XXXX (complex*16 precision) and sparseR8_XXXX (real*8). The superlu_mod.f90 file also contains two test units (sparseC16_test and sparseR8_test) that exercise the library. We recommend Fortran users to study the C API and look at supralu_mod.f90 (described in FAPI_txt/) for examples of Supralu C API calls. There are cases where it is preferable to short-circuit the Fortran API and use directly the C API calls. For instance, if a system needs to be solved repeatedly with different right hand side vectors, it would be wasteful to recompute the LU decomposition of the matrix (as performed in sparseC16_solve for instance). The small granularity of the C API allows you to solve the system using a precomputed LU decomposition. There is more or less a one-to-one mapping between the C and Python APIs. Python is, however, much more dynamical than C and Fortran. In supralu_mod.f90 for instance, the matrix rank and (approximate) number of non-zero values must be known before filling the matrix elements in the sparse matrix object. The Python API on the other hand uses dictionary to store the non-zero matrix elements. Elements can be added and removed at will and need not be filled in any order. The solution of a sparse system is a list in Python. Moreover, there is no need to destroy explicitly the Supralu object, the destructor will be called automatically when the object leaves its scope. Care has been taken in the Python API to prevent memory leaks by testing {d,z}supralumodule.c using a Python version with reference counting turned on. "Live" documentation system: Fortran users can type: $ doc --all for a complete overview of the routines $ doc --routine to access the calling syntax. For instance $ doc --routine sparseR8_error supralu_mod.f90 prints ------------------------------------------- SUBROUTINE sparseR8_error(this, nunit, ier) =========================================== ! Error handler type(sparseR8_obj) :: this integer, intent(in) :: nunit ! output channel integer, intent(in) :: ier ------------------------------------------- Python users can type: pydoc -g which will fire a graphical user interface.