Oblio - version 2.0 (June 1999) 
===============================

General information
-------------------

Oblio is a software package that computes the solution of
sparse linear systems of equations using direct methods.
Oblio 2.0 handles only symmetric systems, both real
and complex valued, with or without pivoting. This
version is also limited to serial platforms;  parallel code 
has been  developed and it is currently being tested and tuned
for better performance.

Oblio is written mostly in C++ using object-oriented techniques.
This makes the code easy to understand, modify and
extend. Portability may be an issue though,  since a standard
for C++ was only recently established and all compilers
do not follow it. Oblio is currently compiled with the GNU's
g++, and since this compiler is available on many platforms,
portability problems can be reduced. To achieve good performance,
a very small (but also very expensive) part of Oblio is written
in Fortran 77. This represents a collection of low level computationally
intensive kernels which account for most of the execution time.

Oblio is organized as a collection of classes stored in a library.
Thus application software must include Oblio's header files and
link with Oblio's library. However, Oblio can also be used as a
standalone tool, a driver program being provided with the package.

Installation
------------

Oblio is distributed as a zipped tar file (oblio.tar.gz). To install
it, the following commands must be typed at the Unix prompt:

> gzip oblio.tar.gz
> tar xvf oblio.tar

After these two steps a directory called oblio is created and the
tar file can be removed. The oblio directory has the following
structure:

Copyright - copyright file
Makefile - general makefile
include/ - header files
lib/ - library source files and library makefile
bin/ - driver source file and driver makefile
data/ - coefficient matrix files
doc/ - documentation

The next step is to build the library and the driver. To do this,
the general Makefile, which is included by the library and driver makefiles
must be customized. The following lines must be edited:

OBLIO_HOME = <type the pathname for the oblio directory>
CCOMPILE = <type the name of the C++ compiler>
CFLAGS = <type the C++ compiler flags>
FCOMPILE = <type the name of the Fortran 77 compiler>
CFLAGS = <type the Fortran 77 compiler flags>
LINK = <type the name of the linker>
LFLAGS = <type the linker flags>

Finally, switch to the lib directory, type make and wait for the
Oblio library (oblio.a) to be built. Repeat the process in the bin
directory, where the Oblio driver (oblio) is built. Oblio is now ready
to be used.

Running the Oblio driver
------------------------

The easiest way to get used to Oblio is by running the Oblio driver.
This is a simple program that loads a sparse matrix from a file,
factors it into a product of triangular and diagonal shaped matrices
and then solves a sequence of triangular and diagonal systems. The
matrix to be loaded represents the coefficient matrix A of a linear system
of equations Ax=b, where x is the solution to be computed and b is the
right hand side. The right hand side must be known too in order to
compute x. It can be loaded from a file, like the coefficient matrix,
but a simple right hand side can be automatically generated by Oblio.
Also, the solution may be saved to a file.

A small set of coefficient matrix files are distributed with Oblio.
They lie in the Oblio data directory and have the mat suffix.

When typing (while in the Oblio bin directory)

> oblio

at the Unix prompt, the driver prints the oblio command line.
This contains the name of the driver (oblio), followed by the
name of a coefficient matrix file, followed by a sequence of options.
The simplest execution does not include any option. For example,
to solve a system with the coefficient matrix stored in the
bcsstk01.lcr.mat file, the following must be typed:

> oblio ../data/bcsstk01.lcr.mat

The output of the driver contains various statistics: the dimensions
of the problem, the storage and execution time requirements, the
performance achieved while doing arithmetic work and the backward
error.

The execution can be customized by using the following options:

[-o order_type]: Use a particular ordering algorithm. Oblio does
not provide ordering algorithms. When this option is not used a
natural order is assumed. The only order type currently supported
in the command line is 1, which stands for multiple minimum degree.
However, the code is not really part of Oblio but rather borrowed
from a package written by Alan George and Joseph Liu. It is
distributed with Oblio for convenience since a natural order may
be extremely expensive.

[-p permutation]: Load or save the permutation to a file. When
the previous option is not specified, the permutation is loaded
from the specified file. Otherwise multiple minimum degree is run,
the permutation obtained is saved in the specified file and the
driver terminates without computing the solution.

[-t threshold]: Use a particular threshold for pivoting. When
not specified or when specifying a value outside the (0,1) range,
no pivoting is performed.

[-v load_values]: Load values from the matrix file. When not specified
no attempt is made to load the numerical entries from the file. Instead,
only the sparsity pattern is loaded and default numerical entries
are automatically generated. The default values make the matrix positive
definite so no pivoting is performed, even if a valid threshold is specified.

[-b right_hand_side}: Load the right hand side from the specified file.
Otherwise a simple right hand side is automatically generated.

[-x solution]: Save the solution to the specified file. Otherwise
the solution is not saved.

[-i number_of_iterations]: Perform the specified number of steps of
iterative refinement. These may be needed when the specified threshold
leads to less pivoting but to a larger backward error.

Numerical values
----------------

Oblio can handle both real and complex valued problems. For this,
all the numerical classes are templatized. For real valued problems
the templates must be instantiated with double while Complex (defined
within Oblio) must be used for complex valued problems. The driver
is initially configured for real valued problems but it can be changed
by replacing the line

#define ValueType double

with

#define ValueType Complex

and building it again.

One has to make sure that the driver matches the matrix file.
Some files store only the sparsity pattern and can be used
with both real and complex valued drivers. Also, any matrix
file can be used with both drivers as long as the command line
does not request the values to be loaded from the file.

Outline of the computation
--------------------------

Oblio solves linear systems directly. It decomposes the coefficient
matrix into a product of triangular and diagonal shaped factors and
then solves the resulting sequence of triangular and diagonal shaped
systems. To preserve sparsity throughout the computation the factorization
phase must be preceded by an ordering one. Oblio does not provide
ordering algorithms, so other packages must be used for this purpose.
For convenience, a multiple minimum degree algorithm code is borrowed
from a package written by Alan George and Joseph Liu and distributed
with Oblio.

The computation begins by loading the coefficient matrix from a file
and preparing a permutation of it. The permutation can be initialized
as natural (expensive), computed using the multiple minimum degree algorithm
or loaded for a file.

Next an elimination forest is computed from the coefficient matrix
and permutation. This is a structure that guides both the factorization
and the solve algorithms. It is followed by a symbolic object, an
entity that stores the sparsity pattern of the factors.

The factors are then computed by running the factorization algorithm.
Oblio uses the multifrontal factorization, which requires an additional
data structure: an update stack. After the factorization the elimination
forest needs to be recomputed if pivoting was performed.

The factorization algorithm is followed by the solve algorithm, which
computes the solution of the system. The solve algorithm may be further
used in a number of steps of iterative refinement if the solution needs
to be improved.

All these steps can be easily identified in the source code of the driver.

Data files
----------

Few coefficient matrices are available in the Oblio data directory:

bcsstk01.lcr.mat
bcsstk14.lcr.mat
e05r0000.lcr.mat
shell.lcr.mat

The first one is a toy size problem useful for testing. The other three
are also fairly small. The "lcr" stands for Lower triangle, Compressed,
Real valued. Some of these matrices have zero on the diagonals and thus
need pivoting.

More information
----------------

At this moment Oblio lacks detailed documentation. More information
can be obtained from the following papers or by contacting the authors. 

Florin Dobrian, Gary Kumfert, and Alex Pothen:
"Object-Oriented Design for Sparse Direct Solvers",
in "Computing in Object-Oriented Parallel Environments",
(Lecture Notes in Computer Science - volume 1505)
Springer-Verlag 1998, pages 207-214.

Florin Dobrian, Gary Kumfert, and Alex Pothen:
"The Design of Sparse Direct Solvers Using Object-Oriented Techniques",
in "Modern Software Tools in Scientific Computing",
A. M. Bruaset, H. P. Langtangen, and E. Quak (eds.), 45 pp., 
Springer-Verlag 1999. To appear. 

These papers are also available from 
www.cs.odu.edu/~pothen/papers.shtml

Florin Dobrian and Alex Pothen
Computer Science Department 
Old Dominion University 
Norfolk VA 23529-0162 

Email: dobrian@cs.odu.edu
       pothen@cs.odu.edu
