Sorry, this project is no longer being maintained.

Persistent Matrix

Introduction

PersistentMatrix aims to be a datatype written for the Clojure Programming Language. Clojure is a relatively new and exciting programming language. It delivers elegantly on its six major features:

1. Dynamic Development
2. Functional Programming
3. Lisp
4. Runtime Polymorphism
5. Concurrent Programming
6. Hosted on the JVM

The motivation behind this project is to complement Clojure already fantastic set of datatypes with another that has significantly different properties but maintains the core design principles of Clojure.

One of the target use cases for the PersistentMatrix datatype is scientific computing. The combination of Java’s libraries and speed along with Clojure’s elegance and flexibility could make an excellent environment for data processing and mathematical exploration. One of the most promising aspects of a scientific environment in Clojure is being able to directly interface scientific exploration with practical application. Anyone who finds themselves excited by this prospect shouldn’t hesitate to learn more about Clojure as well as this datatype and contribute to the growth of the community.

Planned Features

1. Immutability
2. Primitive Support
3. N-Dimensional – Arbitrary number and size of dimensions (ie. ability to create a 4×3×5x6 datastructure)
4. N-Dimensional units (ie. ability to create a 10×10 matrix with 2×1 units to represent complex numbers)
5. Fast submatrix views via structural sharing (ie. constant time slicing, transposing, and other data manipulations)
6. Maintenance of both deep and superficial dimensionality (ie. slicing a 4×3×5x6 along the 3rd dimension will yield a datastructure with a superficial dimensionality of 3 and a deep dimensionality of 4)
7. Axis and element labeling and label indexing (ie. ability to label axes and elements of an axis with strings or any arbitrary object)
8. Implementing many of the clojure interfaces and thereby automatically inheriting much of the functionality of the standard library for data structures.

Getting Started

Before exploring, you should be aware that this library is an early stage of development, and this brief tutorial assumes a functioning Clojure installation and a bit of knowledge about Clojure programming.

Once you have persistentmatrix.jar in your CLASSPATH, you can begin by running the test.clj file at src/clj/test.clj by running clojure test.clj while in the src/clj directory. You can then either inspect that file or continue on with this brief introduction.

To import the datatype class enter the following at the REPL:

(ns matrix
  (:import
   (persistentmatrix.core PersistentMatrix)))

Then to create a new persistentmatrix object enter

(def m (PersistentMatrix/create (int-array [1]) [1 2 3 4 5 6 7 8 9 10] true))

The arguments to this function are the unit shape, the things that will go into this array and a boolean indicating whether this matrix should contain primitive types or not. The second argument which contains the elements of the array can be nested arbitrarily deeply and can be a nested array, a nested object that implements the List interface or a nested object that implements the ISeq interface. This list includes virtually all of the collections in Java and Clojure.

If you’d like to access one of the elements of this array you can do it like this:

(.index m (int-array [3]))

and if you would like to slice into an array, you can do it like this:

(nth m 3)

where nth slices in the last dimension (in this case, the only dimension).

Next you can reshape this one dimensional persistentmatrix into something more interesting (2-dimensions, 5×2):

(def m2 (.reshape m (int-array [5 2])))

Next, let’s add some labels to our dimensions:

(def m2-w-al 
   (.addLabels m2 
      [:colors :shapes] 
      [[:red :yellow :orange :green :blue] [:square :circle]]))

This has the effect of adding labels to our 5×2 matrix where the first dimension is labeled colors and the 5 elements of that dimension are labeled red yellow orange green and blue and the second dimension is labeled shapes and the 2 elements of that dimension are square and circle. You can access the stored labels with the methods getALabels and getELabels.

In the words of the much admired Abelson and Sussman, “Programs must be written for people to read, and only incidentally for machines to execute.” In that spirit, support for labels have been included in the core library for the persistentmatrix. The idea is that labels will do a great deal to ease human interaction with large amounts of complex data.

As of yet, the labels do not do much, but the intention is to eventually make a persistentmatrix a function of its indices and/or labels. For example, one might access an element in a 3-dimensional persistentmatrix like this (note: this functionality doesn’t actually exist yet!):

(m 3 2 5)

or like this:

(m {:subject 3 :trial 2 :time 5})

or like this:

(m {:subject "third" :trial "second" :time "50 msec"})

Have fun!