Compiling and Installing
------------------------

If checking out code from a repository, run

  ./autogen or bash autogen

to regenerate the configure scripts. You will need m4 and the autoconf tools installed to
regenerate these scripts. If these are not available then download the tar ball
which has the configure scripts pre-generated for you. (meagre-crowd-X.Y.Z.tar.gz)

Make sure the prerequists are available, including MPI.
You may need to add the MPI bin directory to the path.
Invoke with bash

  bash get_dependencies.sh

to list all possible options. Decide which solvers to install (mumps, umfpack, pardiso, wsmp, superlu), as you probably don't need all of them. Install the dependencies needed by your solvers. A proper dependency system via Gentoo, Ubuntu, or RedHat should be able to provide most of the dependencies. A list on needed dependencies for each solver does not exist as part of this project yet.

If you have all needed dependencies for meagre-crowd already installed, make sure to set the paths, which are usually set in get_dependencies.sh.

Run the following commands to compile this program

  ./configure
  make
  make install

Run

  ./configure --prefix=<dir>

to have the files installed in a different location from the
default /usr/local (i.e. if you don't have root permission
and would like to install it in your home directory)

If you've used the get_dependancies script then you probably
want to run configure with

  ./configure LDFLAGS="-L$PWD/$(gcc -dumpmachine)/lib -Wl,-rpath,$PWD/$(gcc -dumpmachine)/lib" CPPFLAGS="-I $PWD/$(gcc -dumpmachine)/include" --prefix=$PWD/installed --enable-debug=yes --with-all-solvers

or something similar. The -L and -I directories should be
current locations for the files, while the -rpath should
be the final installed location.


Running the Tests
-----------------

To execute the test suite run

make check


Preparing for Distribution
--------------------------

To tar the archive, then expand, compile and run the test suite

  make distcheck

or, for local dependencies

  make distcheck DISTCHECK_CONFIGURE_FLAGS="LDFLAGS=\"-L$PWD/$(gcc -dumpmachine)/lib -Wl,-rpath,$PWD/$(gcc -dumpmachine)/lib\" CPPFLAGS=\"-I $PWD/$(gcc -dumpmachine)/include\""


Running the Program
-------------------

You can get test matrices from the University of Florida Sparse
Matrix collection. The first 292 matrices of the Univesity of
Florida collection are the Harwell-Boeing Sparse Matrix
collection, so you don't need to download both.

  http://www.cise.ufl.edu/research/sparse/matrices

For usage information, run without any options

  meagre-crowd

For help indicating what the program can do, run

  meagre-crowd --help

To load a matrix 'A' to solve using the default solver, using 2 MPI
processes, show some info on the matrix and time the solving of it:

  mpirun -n 2 ./meagre-crowd -i tests/test.mtx -v -t

Note that you probably also need to submit a job to a scheduler if
you are on a larger multicore system. (bsub, qsub, sqsub?)

File types:

Currently, meagre-crowd determines file type from extensions,
it can only handle MatrixMarket format which it expects to have
a .mtx extension. Rutherford-Boeing and Harwell-Boeing would be
.rb and .hb respectively.

Matrix Sizes:

The equation 'Ax=b' is solved for 'x', where 'A' is a m-by-n matrix
(m rows, n columns), then the right-hand side 'b' is m-by-p, where
having more than a single column in 'b' (p columns) is equivilant
to requesting multiple solutions to the equation, once per-column.
The result 'x' will be an n-by-p matrix.

Right-hand Sides:

The right-hand side of the equation (the 'b' in 'Ax=b') is selected
based on (in priority order)
 1. if a right-hand side is specified on the command-line (--rhs, -b),
 2. if the input matrix file has a right-hand side stored in the file
    (a warning is produced if one is specified on the command-line as
     well) or,
 3. as a last resort a right-hand side is generated.
A right-hand side is generated by creating a single vector (1 column,
and with number of rows matching the matrix A). The values of the
vector match the row index, starting at 1 for the first row.

Contact Us
----------

Discussion and announcements regarding Meagre-Crowd are via the
mailing list (http://groups.google.com/group/meagre-crowd)

Patches, discussion, and suggestions are welcome!

Software is available at http://github.com/boyle/meagre-crowd.
Issues and bugs can be logged in the github issue tracker.
Publications and a couple of academic presentations are also
available. (http://www.sce.carleton.ca/~boyle/software.html)

See the AUTHORS file, for a list of contributors.