Universal Java Matrix Package
A Dense and Sparse Matrix Library for Java

Quick Links

Online Matrix Calculator Download Documentation

Features

The Universal Java Matrix Package provides various visualization methods, import and export filters for various file formats, and the possibility to link to JDBC databases. Multi-dimensional dense and sparse matrices as well as generic matrices with a specified object type are supported and very large matrices can be handled even when they do not fit into main memory.

For UJMP, everything is a matrix: an array of bytes or numbers in main memory, a CSV file on disk, a Java ArrayList or HashMap, a PNG/JPG/GIF image, an Excel spreadsheet, a database table in an SQL database, the database itself with its list of tables, a directory on disk, a ZIP file with the compressed files, and so on.

The central concept to achieve this flexibility is the strict separation of interfaces, abstract classes and their implementations, which makes it very easy to exchange the underlying data storage. In fact, the actual storage implementation becomes secondary and UJMP can even integrate other matrix libraries such as Jama and Colt, which enables UJMP's visualization methods and import/export filters for these libraries.

UJMP uses multiple threads, which results in much better performance compared to JAMA or Colt. To speed up processing even more, calculations can be redirected to other matrix libraries such as jblas, EJML or Ojalgo, depending on matrix size and computer hardware.

There are also interfaces to Matlab, Octave and R, which makes it easy to perform functions not available in Java.

This is the feature list:

• Matrix classes for different data types
  BigDecimalMatrix, BigIntegerMatrix, BooleanMatrix, ByteMatrix, DoubleMatrix, FloatMatrix, IntMatrix, LongMatrix, ObjectMatrix, ShortMatrix and StringMatrix
• Generic Matrix class
  Use GenericMatrix<T> to specify the object type that is stored.
• n-dimensional matrices
  You can create matrices with any number of dimensions with

  Matrix.Factory.sparse(rows, columns, zAxis, ...)

• Storage of more data than fits into memory
  Matrices can be mapped to hard disk or databases.
• Store up to 2⁶³-1 elements along one axis in a matrix
  UJMP uses long values for indices instead of int.
• Link to JDBC data sources
  Work directly with your database:

  Matrix.Factory.linkToJDBC(host, port, db, table, user, password)

• Store meta-data for all matrices
  It is easy to label rows and columns or give a name to the matrix.
• Interact with other matrix libraries
  Use Colt or Jama inside UJMP. In fact, you can tell UJMP to prefer a specific matrix implementation over its own classes.
• Interfaces to other mathematical software
  Execute complex computations in Matlab, Octave, R or GnuPlot. You can use these software packages as computing or visualization engines in UJMP.
• Import and export filters for many different file types
  TXT, CSV, PNG, JPG, GIF, BMP, XLS, XLSX, HTML, XML, JSON, PDF, LaTex, MAT (Matlab), MDB (MS Access), and many more.
• Link to huge CSV files without loading them into memory
  This is useful when your CSV file does not fit into your machine's memory. Use

  Matrix.Factory.linkTo().file("hugeCSVFile").asDenseCSV(columnSeparator)

• Additional collection classes
  e.g. CachedMap, RingBufferList or SoftHashMap which can be very helpful.
• Store more objects than fit into memory
  SerializedObjectMapThis stores all objects on disk and can be used like a normal HashMap.
• Mapping of collection classes
  Java collection classes like Map, List or Set can be used as UJMP matrices, which makes it easy to perform calculations. E.g. you can calculate sum, average or standard deviation of a list of values in an ArrayList. Use this to convert it to a UJMP matrix:

  Matrix.Factory.linkToCollection(myArrayList)

• Visualization
  Heatmap, line plot, scatter plot, histogram and many more. Just use myMatrix.showGUI() to bring it on the screen. Take a look at the screenshots for examples.
• Licensed under LGPL
  you can use it in commercial applications.

Too good to be true?

Well, to be perfectly honest with you, there are some things you will not like about UJMP, so here is the list why you may not want to use it:

The Universal Java Matrix Package is...

• ...not finished
  While some parts are already pretty stable, a lot of development is still going on in other areas. There is no guarantee that everything will be working as expected. Be prepared for renamed methods and interfaces from one version to the next.
• ...not well documented
  Since many things are going to change anyway, we didn't bother to write much documentation.
• ...not a lightweight matrix library
  If you just need linear algebra for double matrices, there are probably better choices, such as EJML or Ojalgo.

Wanna help?

Developers are welcome to contribute new features, test cases or documentation.

If you like this library and it does something useful for you, a small donation will be very much appreciated to help cover server costs and ensure the coffee supply for further development.

Thank you very much for supporting open source software!

Donate via PayPal

Documentation

Quick Start

// create a dense empty matrix with 4 rows and 4 columns
Matrix dense = DenseMatrix.Factory.zeros(4, 4);

// set entry at row 2 and column 3 to the value 5.0
dense.setAsDouble(5.0, 2, 3);

// set some other values
dense.setAsDouble(1.0, 0, 0);
dense.setAsDouble(3.0, 1, 1);
dense.setAsDouble(4.0, 2, 2);
dense.setAsDouble(-2.0, 3, 3);
dense.setAsDouble(-2.0, 1, 3);

// print the final matrix on the console
System.out.println(dense);

// create a sparse empty matrix with 4 rows and 4 columns
Matrix sparse = SparseMatrix.Factory.zeros(4, 4);
sparse.setAsDouble(2.0, 0, 0);

// basic calculations
Matrix transpose = dense.transpose();
Matrix sum = dense.plus(sparse);
Matrix difference = dense.minus(sparse);
Matrix matrixProduct = dense.mtimes(sparse);
Matrix scaled = dense.times(2.0);

Matrix inverse = dense.inv();
Matrix pseudoInverse = dense.pinv();
double determinant = dense.det();

Matrix[] singularValueDecomposition = dense.svd();
Matrix[] eigenValueDecomposition = dense.eig();
Matrix[] luDecomposition = dense.lu();
Matrix[] qrDecomposition = dense.qr();
Matrix choleskyDecomposition = dense.chol();

Random Matrix

// create matrix with random values between 0 and 1
Matrix rand = Matrix.Factory.rand(100, 10);

// create matrix with random values between -1 and - 1
Matrix randn = Matrix.Factory.randn(100, 10);

// show on screen
rand.showGUI();
randn.showGUI();

Cosine Similarity Matrix

// create matrix with 10 correlated columns, 100 rows, correlation 0.1
Matrix correlated = Matrix.Factory.correlatedColumns(100, 10, 0.1);

// calculate similarity and store in new matrix,
// ignore missing values if present
Matrix similarity = correlated.cosineSimilarity(Ret.NEW, true);

// show on screen
correlated.showGUI();
similarity.showGUI();

Image Matrix

// get an image
InputStream is = ClassLoader.getSystemClassLoader().getResourceAsStream("org/ujmp/examples/data/bigdata.jpg");

// load image into matrix. of course, this works with files, too.
Matrix imageMatrix = new ImageMatrix(is);

// show on screen
imageMatrix.showGUI();

is.close();

Localhost Matrix

// create a matrix representing the local computer with its services
Matrix localhost = Matrix.Factory.localhostMatrix();

// show on screen
localhost.showGUI();

// double click on matrix entries to navigate and see how everything is
// a matrix. Have fun exploring, but be careful when you change data!

Big Sparse Matrix

// create a very large sparse matrix
SparseMatrix m1 = SparseMatrix.Factory.zeros(1000000, 500000);

// set some values
m1.setAsDouble(MathUtil.nextGaussian(), 0, 0);
m1.setAsDouble(MathUtil.nextGaussian(), 1, 1);
for (int i = 0; i < 10000; i++) {
	m1.setAsDouble(MathUtil.nextGaussian(), MathUtil.nextInteger(0, 1000), MathUtil.nextInteger(0, 1000));
}

// show on screen
m1.showGUI();

// create another matrix
SparseMatrix m2 = SparseMatrix.Factory.zeros(3000000, 500000);

// set some values
m2.setAsDouble(MathUtil.nextGaussian(), 0, 0);
m2.setAsDouble(MathUtil.nextGaussian(), 1, 1);
for (int i = 0; i < 10000; i++) {
	m2.setAsDouble(MathUtil.nextGaussian(), MathUtil.nextInteger(0, 1000), MathUtil.nextInteger(0, 1000));
}

// show on screen
m2.showGUI();

// do some operations
Matrix m3 = m1.mtimes(m2.transpose());

// show on screen
m3.showGUI();

Extract Excel Data

// find all Excel files in one directory
File[] files = new File("c:/temp/").listFiles();

// create matrix to store result
Matrix result = Matrix.Factory.zeros(files.length, 2);

// iterate over all files
for (int i = 0; i < files.length; i++) {

	// import file as matrix
	Matrix m = Matrix.Factory.importFrom().file(files[i]).asDenseCSV();

	// store file name in result matrix
	result.setAsString(files[i].getName(), i, 0);

	// search for "Invoice"
	if (m.containsString("Invoice"))

		// extract value at row 10 and column 3 and store in result
		result.setAsDouble(m.getAsDouble(10, 3), i, 1);
}

// display result on screen
result.showGUI();

Graph Matrix

// create a GraphMatrix with Strings as nodes and Doubles as edges
GraphMatrix<String, Double> graphMatrix = new DefaultGraphMatrix<String, Double>();
graphMatrix.setLabel("Interface Inheritance Graph");

// collect all matrix interfaces from UJMP
Class<?>[] classArray = new Class[] { DenseMatrix.class, DenseMatrix2D.class, Matrix.class, Matrix2D.class,
		SparseMatrix.class, SparseMatrix2D.class, BaseBigDecimalMatrix.class, BigDecimalMatrix2D.class,
		DenseBigDecimalMatrix.class, DenseBigDecimalMatrix2D.class, SparseBigDecimalMatrix.class,
		SparseBigDecimalMatrix2D.class, BigIntegerMatrix.class, BigIntegerMatrix2D.class,
		DenseBigIntegerMatrix.class, DenseBigIntegerMatrix2D.class, SparseBigIntegerMatrix.class,
		SparseBigIntegerMatrix2D.class, BooleanMatrix.class, BooleanMatrix2D.class, DenseBooleanMatrix.class,
		DenseBooleanMatrix2D.class, SparseBooleanMatrix.class, SparseBooleanMatrix2D.class,
		ByteArrayMatrix.class, ByteArrayMatrix2D.class, DenseByteArrayMatrix.class,
		DenseByteArrayMatrix2D.class, SparseByteArrayMatrix.class, SparseByteArrayMatrix2D.class,
		ByteMatrix.class, ByteMatrix2D.class, DenseByteMatrix.class, DenseByteMatrix2D.class,
		SparseByteMatrix.class, SparseByteMatrix2D.class, CharMatrix.class, CharMatrix2D.class,
		DenseCharMatrix.class, DenseCharMatrix2D.class, SparseCharMatrix.class, SparseCharMatrix2D.class,
		DoubleMatrix.class, DoubleMatrix2D.class, DenseDoubleMatrix.class, DenseDoubleMatrix2D.class,
		SparseDoubleMatrix.class, SparseDoubleMatrix2D.class, FloatMatrix.class, FloatMatrix2D.class,
		DenseFloatMatrix.class, DenseFloatMatrix2D.class, SparseFloatMatrix.class, SparseFloatMatrix2D.class,
		GenericMatrix.class, GenericMatrix2D.class, DenseGenericMatrix.class, DenseGenericMatrix2D.class,
		SparseGenericMatrix.class, SparseGenericMatrix2D.class, IntMatrix.class, IntMatrix2D.class,
		DenseIntMatrix.class, DenseIntMatrix2D.class, SparseIntMatrix.class, SparseIntMatrix2D.class,
		LongMatrix.class, LongMatrix2D.class, DenseLongMatrix.class, DenseLongMatrix2D.class,
		SparseLongMatrix.class, SparseLongMatrix2D.class, ObjectMatrix.class, ObjectMatrix2D.class,
		DenseObjectMatrix.class, DenseObjectMatrix2D.class, SparseObjectMatrix.class,
		SparseObjectMatrix2D.class, ShortMatrix.class, ShortMatrix2D.class, DenseShortMatrix.class,
		DenseShortMatrix2D.class, SparseShortMatrix.class, SparseShortMatrix2D.class, StringMatrix.class,
		StringMatrix2D.class, DenseStringMatrix.class, DenseStringMatrix2D.class, SparseStringMatrix.class,
		SparseStringMatrix2D.class };

// find out how interfaces extend one another
for (Class<?> c1 : classArray) {
    for (Class<?> c2 : classArray) {
        if (c2.getSuperclass() == c1) {
            // add edge when class2 extends class1
            graphMatrix.setEdge(1.0, c1.getSimpleName(), c2.getSimpleName());
        }
    for (Class<?> c3 : c2.getInterfaces()) {
			if (c1 == c3) {
				// add edge when class2 implements class1
				graphMatrix.setEdge(1.0, c1.getSimpleName(), c2.getSimpleName());
			}
		}
	}
}

// show on screen
graphMatrix.showGUI();

Mandelbrot Matrix

// create a matrix from the Mandelbrot set
Matrix m = new MandelbrotMatrix();

// show on screen
m.showGUI();

Tree Matrix

// create a TreeMatrix with Strings as elements
TreeMatrix<String> treeMatrix = new DefaultTreeMatrix<String>();

// create data
treeMatrix.setRoot("root");
treeMatrix.addChild("root", "child1");
treeMatrix.addChild("root", "child2");
treeMatrix.addChild("root", "child3");
treeMatrix.addChild("child1", "subChild11");
treeMatrix.addChild("child1", "subChild12");
treeMatrix.addChild("child1", "subChild13");
treeMatrix.addChild("child2", "subChild21");
treeMatrix.addChild("child3", "subChild31");
treeMatrix.addChild("child3", "subChild32");
treeMatrix.addChild("subChild12", "subSubChild121");
treeMatrix.addChild("subChild12", "subSubChild122");
treeMatrix.addChild("subSubChild122", "subSubSubChild1221");

// show on screen
treeMatrix.showGUI();

List of UJMP Modules