Read Me

---------------------------------------------
DESCRIPTION
---------------------------------------------

This is an implementation of the high-order Multivariate Interpolation and
Regression schcme, developped by Qiqi Wang et. al.  The mathematical
formulation and some example usage of this scheme is described in the paper
"A High-Order Multi-Variate Approximation Scheme for Arbitrary Data Sets"
by Qiqi Wang et. al, submitted to the Journal of Computational Physics.

Information about this code can be found at http://mirscheme.sourceforge.net/


---------------------------------------------
PREREQUISITES
---------------------------------------------

Gnu Scientific Library:
http://www.gnu.org/software/gsl/

Python 2.5 or newer compatible version (Optional for Python interface):
http://www.python.org/

Numpy 1.2 or newer compatible version (Optional for Python interface):
http://numpy.scipy.org/

Matplotlib 0.98 or newer compatible version (Optional for test scripts of
Python interface):
http://matplotlib.sourceforge.net/


---------------------------------------------
INSTALLATION
---------------------------------------------

1. Edit the Makefile to specify:
    prefix -- the desired installation location,
    GSL_prefix -- where Gnu Scientific Library is located,
    CC -- C compiler,
    FC -- Fortran compiler,
    CFLAGS -- Compiler flags,
    LFLAGS -- Linker flags.

2. "make".

3. "make install"

4. (Optional) "make check" to build and run test scripts in C and Fortran.

5. (Optional for Python interface) "python setup.py build".
   Note: if it complains "cannot find Python.h", you need to install the
         Python header files. Either install Python from source file, or
         install the 'development' package, such as the 'python-dev'
         package in Ubuntu.

6. (Optional for Python interface) "python setup.py install",
   or "python setup.py install --prefix=(your location)" to install at
   non-standard locations.

7. (Optional for testing Python interface) "python test.py".


---------------------------------------------
USAGE
---------------------------------------------

This C implementation of the approximation has procedural interfaces in
both C and Fortran, plus an object oriented interface in Python.

C interface:
    Three functions should be mostly used.  The specification of these
    functions are given in mir.h.
    binomialInv:  Calculate the largest value of m such that
                  binomial(m, n) <= l
    mirBetaGamma: Automatically calculate the parameters of the
                  approximation scheme.
    mirBasis:     Calculate the values of the basis functions at
                  specified points.
    mirEvaluate:  Calculate the value of the approximation function
                  at specified points.

Fortran interface:
    The Fortran interface has four subroutines that accomplishes
    exactly the same work as the C functions.  The specification for
    these Fortran subroutines are the same as the C functions found
    at mir.h.  Sample usage is given in test.f.  The correspondence
    between Fortran subroutines and C functions is:
    BINOMIAL_INV(l, n, m) -- m = binomialInv(l, n),
    MIR_BETA_GAMMA(*)     -- mirBetaGamma(*),
    MIR_BASIS(*)          -- mirBasis(*),
    MIR_EVALUATE(*)       -- mirEvaluate(*).
    * All arguments are the same, the return value from C functions that
      indicates error status is ignored.

Python interface:
    The Python interface provides an Object Oriented way of accessing
    the approximation scheme.  This interface consists of a Python class
    mir.Mir, which exposes the functionality of the C code in a more
    user-friendly way.  Detailed specification of the interface
    can be found in mir.py.  This specification can also be obtained by
    "help(mir)" after "import mir" in Python command line.  Example usage
    of the Python interface can be found in test.py


---------------------------------------------
SUPPORT
---------------------------------------------

This code is maintained and supported by

Qiqi Wang
Assistant Professor of Aeronautics and Astronautics,
Massachusetts Institute of Technology,
Building 33, Room 408,
77 Massachusetts Ave,
Cambridge, MA 02139.

Email: qiqi@mit.edu
Phone: 617-253-0921