parrot-linear-algebra
A linear algebra library package for the Parrot Virtual Machine
== PROJECT GOALS ==
The goals of the Parrot-Linear-Algebra (PLA) project are to develop a good,
high-performance linear algebra toolset for use with the Parrot Virtual
Machine, and programs that run on top of Parrot. In pursuit of these goals,
high-performance PMC matrix types will be developed, along with interfaces
to the BLAS and LAPACK libraries for high-performance operations.
In addition to these core goals, PLA may also provide a series of ancillary
tools that are similar in implementation to it's high-performance core
utilities.
== STATUS ==
PLA is being actively developed. It has core PMC types that build, a build
and installation system, and a growing test suite.
PLA currently provides these PMC types:
* NumMatrix2D
A 2-D matrix containing floating point values.
* PMCMatrix2D
A 2-D matrix containing PMC pointers
* ComplexMatrix2D
A 2-D matrix containing Complex values, optimized to store complex values
directly instead of using an array of Parrot's Complex PMC type.
* CharMatrix2D (Testing)
A 2-D character matrix that doubles as an array of strings with
fixed-row-length storage.
PLA does not yet offer matrix or tensor types with more than two dimensions.
== DEPENDENCIES ==
PLA has several dependencies. To help manage dependencies, you may want
to install Plumage
http://gitorious.org/parrot-plumage
This is not a dependency, just a convenience.
Each PLA release will target different versions of the various dependencies.
See the file RELEASES for information about individual releases and their
dependencies.
Here are a list of dependencies for PLA:
* Parrot 2.7.0
PLA is an extension for Parrot and requires Parrot to build and run.
Releases of PLA will target supported releases of Parrot. Supported
releases are typically X.0, X.3, X.6, X.9. Releases for Parrot can be
retrieved from
http://www.parrot.org
Development between releases will typically target the latest supported
release, though it may begin to target more recent development releases in
anticipation of the next supported release.
PLA expects a built and installed Parrot. For more information about the
installation process
* CBLAS or ATLAS
PLA depends on either CBLAS or ATLAS. The BLAS library is written in
Fortran, so C language bindings are all translations of the Fortran
interface. Unfortunately there is not a good, standard way of translating
the Fortran source to C API bindings, so not all libraries that provide a
C API for BLAS will have an interface compatible with PLA. We are working
to be more accepting of small differences in various interfaces, but this
work is moving slowly.
PLA may eventually support direct linkage to the BLAS library, instead of
requiring a C language implementation (CBLAS or ATLAS). This is not
supported yet but is on the roadmap.
We recommend the ATLAS library for current development and testing work.
On Ubuntu or other Debian-based distros, you can type this incantation to
get it automatically:
sudo apt-get install libatlas3-base
sudo apt-get install libatlas-base-dev
On Fedora you can type:
sudo yum install atlas-devel
Notice that the default vesions of the atlas library are only generally
optimized. If you are able, try to use a platform-specific variant (such
as "-sse2" or "-3dnow") for better performance. See the ATLAS homepage for
more information:
http://math-atlas.sourceforge.net/
* LAPACK
LAPACK is a library of linear algebra routines which rely heavily on the
local BLAS implementation. For more information about LAPACK, see the
project homepage at:
http://www.netlib.org/lapack
LAPACK bindings are currently in development.
* Kakapo
Kakapo is a framework library for the NQP language. PLA currently uses
Kakapo to implement it's unit testing suite. You can build and install
PLA without Kakapo, but you will need the framework to run the test suite.
You can obtain Kakapo from it's source code repository on Gitorious, and
get documentation from its project page on Google Code:
http://gitorious.org/kakapo
http://code.google.com/p/kakapo-parrot/
* Other
Currently, PLA is only tested to build and work on Linux and other
Unix-like systems with all the aforementioned prerequisites. The setup
process pulls configuration information from your installed version of
Parrot, so it will attempt to use the same compiler with the same
compilation options as Parrot was compiled with. If another compiler
absolutely needs to be used, there may be a way to specify that, but no
documentation about the process exists.
== BUILDING ==
To get, build, test, and install Parrot-Linear-Algebra, follow these steps
(on Linux) once all the prerequisites have been prepared:
git clone git://github.com/Whiteknight/parrot-linear-algebra.git pla
cd pla
parrot-nqp setup.nqp build
parrot-nqp setup.nqp test
parrot-nqp setup.nqp install
Testing only works if you have Kakapo installed on your system. To install,
you may need root privileges on your system. There is currently no known way
to build or deploy PLA on Windows.
== DIRECTORY STRUCTURE ==
+ /
+ dynext/ : Location for generated libraries
+ examples/ : Example programs in various languages
+ ports/ : Generated information about porting
+ src/ : Source code
+ include/ : Include files
+ lib/ : Library files
+ pmc/ : PMC definition files
+ nqp/ : The NQP bootstrapper
+ rakudo/ : Wrapper files for use in Rakudo Perl 6
+ t/ : Tests
+ methods/ : Tests for methods
+ pmc/ : Tests for various PMC types
+ testlib/ : Common test library
== CREDITS ==
Original versions were developed as part of the Matrixy project by Blairuk.
Some parts of the test suite were provided by Austin Hastings.
See the file CREDITS for updated information about contributors.