jblas.1.2.1.source-code.overview.textile Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jblas Show documentation
The newest version!
h1. jblas - Linear Algebra for Java

If you are really impatient, I'd suggest you read the Classes
Overview below and otherwise stick to the API Documentation for the
classes like DoubleMatrix.

The main goals of jblas were to provide very high performance, close
to what you get from state-of-the-art BLAS and LAPACK libraries, and
easy of use, which means that in the ideal case, you can just
mechanically translate a matrix expression from formulas to Java
code. 

In all brevity, here is what you need to know to get started:

* There exist four classes: FloatMatrix, DoubleMatrix,
  ComplexFloatMatrix and ComplexDoubleMatrix in the package
  @org.jblas@ which represent real and complex matrices in single and
  double precision.

* Higher-level routines for solving equations, or computing
  eigenvalues are grouped in classes like Eigen, Solve, or Geometry.

* To construct a new matrix, you can either use the constructor, or
  one of the factory methods @ones@ (constructs a matrix of all ones),
  @zeros@, @rand@ (entries uniformly distributed between 0 and 1),
  @randn@ (entries normally distributed), @eye@ (unit matrix), @diag@
  (matrix with given diagonal). Dimensions are specified in the order
  "row", "column". The number of columns defaults to 1 if omitted
  (meaning that you construct a row vector, if you supply just one
  dimension).

* To access elements, you use @put@ and @get@. Methods also exist for
  reading or writing a whole column, row, or submatrix.

* There exist only two-dimensional matrices. Vectors are matrices
  whose number of columns or rows are 1. This has turned out to be
  much more convenient thatn having separated classes.

* Every math operator maps to a short mnemonic name. For example, +
  becomes @add@, - becomes @sub@, * becomes @mul@, / becomes @div@,
  and so on.

* Often, you can pass a double or float value, or a matric with only
  one element as the argument to a method, for example, to add the
  same value to all elements of the matrix.

* @mul@ is element-wise multiplication. Matrix-matrix multiplication
  is called @mmul@.

* Often, you can add an "i" to a method to have it work "in-place". For
  example, @addi@ is like @+=@.

What is missing right now:

* Right now, the four classes more or less exist next to each other,
  with no abstract superclass. This makes the classes pretty
  straightforward, but the downside is that you cannot have a function
  which works with any kind of matrices.

* No support for sparse matrices.

* Not all of LAPACK is covered, only things I'm using myself. In
  principle, there is little overhead in adding further functions as
  the generation of wrappers is automatic, but I'd rather include a
  function from LAPACK only after I'm sure it does what it's supposed
  to do. In other words, I'll happily add anything somebody needs as
  long as he can check whether the method works as it should.

* Build only works for Windows (XP) with Cygwin and Linux. Mac OS X
  would be most welcome, but I don't have access to such a machine.

* jblas uses double and float arrays to store the matrix. Whenever you
  call a native function, the array is first copied. This means that
  it doesn't make much sense to call a native routine if its
  computation is linear in the size of the data, but this includes
  most of BLAS Level 1 and Level 2. jblas therefore uses Java
  implementation for things like vector addition, or even
  matrix-vector multiplication and is therefore not as fast as native
  BLAS. Currently, I'm contemplating some caching schemes to improve
  performance here.