----------------------------------------------------------------------
SaveHB Dynamic Loading Module for FreeFem++

  Hiroshi Fujiwara, fujiwara (ATMARK) acs.i.kyoto-u.ac.jp
----------------------------------------------------------------------

----------------------------------------------------------------------
1. What is this?
----------------------------------------------------------------------

The module SaveHB.cpp is an implementation for FreeFem++ to save
a system of linear equations into a text file in Harwell-Boeing format.

The Harwell-Boeing format is a file format to store a system of linear
equations with Compressed Column Storage (CCS), which is used in, e.g.,
    Matrix Market (http://math.nist.gov/MatrixMarket)
    IML++(http://math.nist.gov/iml++)

----------------------------------------------------------------------
2. Build
----------------------------------------------------------------------

(1) Edit Makefile; Set the appropriate directory, where FreeFem++ was
    installed, into FREEFEMROOT variable according to your environment.
(2) Execute make.
    Then SaveHB.so (Linux, Solaris), or SaveHB.dylib (MacOSX) is generated.

Remark: Windows OS has not been checked.

----------------------------------------------------------------------
3. Test
----------------------------------------------------------------------

(1) Place 'SaveHB.so' and 'sample.edp' in the same directory, and execute
    $ FreeFem++-nw sample.edp
    Then you will get a new file 'sample.hb' there.

(2) Compare 'sample.hb' with 'sample.hb.correct'.

(3) If you get errors such as
    ------------------------------
        load error : SaveHB
                 fail : 
    ------------------------------
    set the directory where SaveHB.so is located to the environment
    variable FF_LOADPATH. For example,

    $ FF_LOADPATH="./" FreeFem++-nw sample.edp   (in bash/zsh)

    $ setenv FF_LOADPATH="./"  (in csh/tcsh)
    $ FreeFem++-nw sample.edp

----------------------------------------------------------------------
4. Usage and Return value
----------------------------------------------------------------------

long SaveHB( HB_filename, A, b, HB_title );

   (1) HB_filename : string, filename for output Harwell-Boeing format
   (2) A : coefficient matrix
   (3) b : right-hand side vector
   (4) HB_title    : string, title of the file stored in HB file format

It returns 0 if success, and returns 1 otherwise.

----------------------------------------------------------------------
5. Examples
----------------------------------------------------------------------
------------------------------
Real Version
------------------------------
matrix A = ...;
real[int] rhs = ...;

load "SaveHB"
SaveHB("filename.hb", A, rhs, "Title of HB file");

------------------------------
Complex Version
------------------------------
matrix<complex> A = ...;
complex[int] rhs = ...;

load "SaveHB"
SaveHB("filename.hb", A, rhs, "Title of HB file");
------------------------------

----------------------------------------------------------------------
End of file
----------------------------------------------------------------------