Manual
The Basics
Efficient Java Matrix Library (EJML) is a Java library for performing standard linear algebra operations on dense matrices. Typically the list of standard operations is divided up unto basic (addition, subtraction, multiplication, ...etc), decompositions (LU, QR, SVD, ... etc), and solving linear systems. A complete list of its core functionality can be found on the Capabilities page.
This manual describes how to use and develop an application using EJML. Other questions, like how to build or include it in your project, is provided in the list below. If you have a question which isn't answered or is confusion feel free to post a question on the message board! Instructions on how to use EJML is primarily done in this manual through example, see below. The examples are selected from common real-world problems, such as Kalman filters. Some times the same example is provided in three different formats using one of the three interfaces provided in EJML to help you understand the differences.
EJML is compatible with Java 1.8 and beyond.
The Interfaces
A primary design goal of EJML was to provide users the capability to write both highly optimized code and easy to read/write code. Since it's hard to do this with a single API BoofCV provides three different ways to interact with it.
- Procedural: You have full access to all of EJML's capabilities, can select individual algorithms, and almost complete control over memory. The downside is it feels a bit like you're programming in assembly and it's tedious to have that much control over memory.
- SimpleMatrix: An object oriented API that allows you to connect multiple operations together using a flow strategy, which is much easier to read and write. Limited subset of operations are supported and memory is constantly created and destroyed.
- Equations: Is a symbolic interface that allows you to manipulate matrices in a similar manor to Matlab/Octave. Can be precompiled and won't declare new memory if the input size doesn't change. It's a bit of a black box and the compiler isn't smart enough to pick the most efficient functions.
Example of compute the Kalman gain "K"
|
Procedural mult(H,P,c);
multTransB(c,H,S);
addEquals(S,R);
if( !invert(S,S_inv) )
throw new RuntimeException("Invert failed");
multTransA(H,S_inv,d);
mult(P,d,K);
SimpleMatrix SimpleMatrix S = H.mult(P).mult(H.transpose()).plus(R);
SimpleMatrix K = P.mult(H.transpose().mult(S.invert()));
Equations eq.process("K = P*H'*inv( H*P*H' + R )");
|
It's hard to say which interface is the best. If you are dealing with small matrices and need to write highly optimized code then Procedural is the way to go. For large matrices it doesn't really matter which one you use since the overhead is insignificant compared to the matrix operations. If you want to write something quickly then SimpleMatrix or Equations is the way to go. For those of you who are concerned about performance, I recommend coding it up first using SimpleMatrix or Equations then benchmarking to see if that code is a bottleneck. Much easier to debug that way.
Comparison of Interface Runtime Performance
Tutorials
- Matlab to EJML
- Complex
- Solving Linear Systems
- Matrix Decompositions
- Random matrices, Matrix Features, and Matrix Norms
- Extracting and Inserting submatrices and vectors
- Matrix Input/Output
- Unit Testing
Example Code
The follow are code examples of common linear algebra problems intended to demonstrate different parts of EJML. In the table below it indicates which interface or interfaces the example uses.
| Name | Procedural | SimpleMatrix | Equations |
|---|---|---|---|
| Kalman Filter | X | X | X |
| Sparse Matrix Basics | X | ||
| Levenberg-Marquardt | X | ||
| Principal Component Analysis | X | ||
| Polynomial Fitting | X | ||
| Polynomial Roots | X | ||
| Customizing Equations | X | ||
| Customizing SimpleMatrix | X | ||
| Fixed Sized Matrices | X | ||
| Complex Math | X | ||
| Complex Matrices | X | ||
| Concurrent Operations | X | ||
| (GraphBLAS) Graph Paths | X | ||
| (GraphBLAS) Masked Triangle Count | X | ||
| Optimizing Large Dense | X |
External References
Want to learn more about how EJML works to write more effective code and employ more advanced techniques? Understand where EJML's logo comes from? The following books are recommended reading and made EJML's early development possible.
- Best introduction to the subject that balances clarity without sacrificing important implementation details:
- Fundamentals of Matrix Computations by David S. Watkins
- Classic reference book that tersely covers hundreds of algorithms
- Matrix Computations by G. Golub and C. Van Loan
- Direct Methods for Sparse Linear Systems by Timothy A. Davis
- Covers the sparse algorithms used in EJML
- Popular book on linear algebra
- Linear Algebra and Its Applications by Gilbert Strang