--------
CONTENTS
--------

This package contains routines to tridiagonalize skew-symmetric
matrices and compute their Pfaffian. It contains routines written in
FORTRAN that are optimized for speed and numerical stability, and can
deal with dense and banded matrices. It also contains code for python
and mathematica that is less optimized, but more intuitive.

The root of the package contains:

 README.txt 		this file
 LICENSE		some notes regarding copyright
 fortran/	     	the implementation in FORTRAN
 fortran/TESTING/	extensive test suite for the FORTRAN
                        implementation
 fortran/EXAMPLES/	example programs in FORTRAN
 c_interface/		a convenient C interface for the FORTRAN routines
 c_interface/TESTING/	test suite for the C interface
 c_interface/EXAMPLES/	example programs in C and C++
 mathematica/		Mathematica implementation
 matlab/                Matlab implementation
 python/		Python implementation + examples


------------
AVAILABILITY
------------

The most recent version of this library, including possible bug fixes
and enhancements, will be available at

http://www.ilorentz.org/~wimmer/downloads.html

------------
REQUIREMENTS
------------

-FORTRAN implementation:
 In order to use the FORTRAN code, one also needs a LAPACK and BLAS
 library (linked, e.g. as -llapack -lblas). Using an optimized LAPACK
 and BLAS will also benefit the speed of this code.

 The FORTRAN implementation uses the LAPACK/BLAS functions LSAME and
 XERBLA. They are sometimes not included in some machine-specific
 precompiled LAPACK and BLAS libraries. In this case you need to
 obtain them from www.netlib.org/blas or www.netlib.org/lapack (files
 lsame.f and xerbla.f).  For more instructions see "Installation"
 below.

-C interface:
 The C interface requires the Fortran implementation to be built
 successfully. It can be compiled with either a C or C++-compiler.

-Mathematica implementation:
 No extra requirements except Mathematica (tested on versions 7 and 8,
 but should also run on earlier versions).

-Matlab implementation:
 No extra requirements except Matlab (tested on version 2010b, but
 should also work on previous versions)

-python implementation:
 The python implementation requires numpy and scipy.

-----------
INSTALLATON
-----------

-FORTRAN implementation:
 In order to compile the FORTRAN library, change fortran/makefile to use
 your favorite compiler and options, and then type "make". Copy
 libpfapack.a to wherever you need it, along with the
 Fortran95 interface modules, if needed.

 If your LAPACK and BLAS library does not contain LSAME and XERBLA
 (this is the case if the example programs fail to compile with the
 linker complaining about missing symbols such as 'lsame_' and
 'xerbla_), obtain lsame.f and xerbla.f
 (e.g. www.netlib.org/blas/lsame.f and www.netlib.org/blas/xerbla.f)
 and put them in fortran/. Finally, add "lsame.o xerbla.o" to the
 OBJECTS, and compile with "make".

-C interface:
 In order to compile the C interface, change c_interface/makefile
 to use your favorite compiler and options, and then type "make".
 Programs using the C interface need pfapack.h, fortran_pfapack.h
 and fortran.h, as well as libcpfapack.a along with the Fortran
 library libpfapack.a.

 Interfacing Fortran from C usually works out of the box, but may require
 some additional input from the user, especially with regard
 to Fortran function names. Please refer to the corresponding
 c_interface/README.txt.

-Mathematica, Matlab and python implementation:
 No particular installation steps required.

----------------
EXAMPLES AND USE
----------------

All implementations are documented extensively in-place in the
respective files.

-FORTRAN implementation:
 The directory fortran/ contains an extensive test-suite checking the
 implementation in the directory TESTING/. Examples are in the
 directory EXAMPLES/. In all cases modify makefile to use your
 favorite compiler and options, as well as your LAPACK and BLAS
 library.

 For dense matrices, the Householder transformations used in the
 skew-symmetric tridiagonalization are stored in the same format as
 used by the symmetric and Hermitian LAPACK tridiagonalization
 routines. Hence, the LAPACK routines xORGTR/xUNGTR can be used to
 form the transformation matrix explicitely, and xORMTR/xUNMTR can be
 used to multiply another matrix with the transformation, without
 forming it explicitely.

-C interface:
 The directory c_interface contains an extensive test-suite that
 checks the C interface for consistency against the Fortran interface.
 Example programs are included in EXAMPLES/, both showing how to
 access the raw FORTRAN77 interface, and the more comfortable
 C interface. In all cases modify makefile to use your
 favorite compiler and options, as well as your LAPACK and BLAS
 library.

 The C interface expects matrices to be given in FORTRAN format. For
 details see c_interface/README.txt.

-Mathematica implementation:
 The file pfaffian.nb contains both the definitions of the routines as
 well as examples. Details are given in mathematica/README.txt

-Matlab implementation:
 The function files must be in a path where Matlab searches for
 external functions (for example, the working directory). Details
 are given in matlab/README.txt

-python implementation:
 Import the implementation to your python program to use the routines.
 A test program is included, the tests can be run using nosetests.
 Details are given in python/README.txt
