JavaPlex Tutorial

In this tutorial we will learn how to use the JavaPlex package in Matlab. For a more complete picture of JavaPlex please visit the projects homepage and consider also reading the tutorial provided there.

Installation

To use JavaPlex with Matlab you will need a working version of Matlab. Furthermore, JavaPlex requires Java version number 1.5 or higher. You can check your Java version in Matlab by entering version -java

To install JavaPlex in Matlab go to the latest release at [1]. Download the zip file of matlab examples, named something like matlab-examples-4.3.4.zip. Unzip the folder to a known location, by default the resulting folder is called matlab_examples.

In Matlab, change your current folder to matlab_examples. Run the script load_javaplex.m that resides in this folder and import the JavaPlex routines provided by the package. You can do this by entering the following commands into the command line

load_javaplex.m;
import edu.stanford.math.plex4.*;

You will need to reload the package with these commands every time you open a new Matlab session.

To check wether JavaPlex was loaded correctly, e.g. enter api.Plex4.createExplicitSimplexStream() which will return something like

ans = edu.stanford.math.plex4.streams.impl.ExplicitSimplexStream@513fd4

Basic constructions

Simplex Streams

JavaPlex implements abstract simplicial complexes via simplex streams, which are provided by the function

 api.Plex4.createExplicitSimplexStream()

To a simplex stream we assign vertices and higher simplices as exemplified below.

Example: 1-sphere

In order to build a simplicial complex by hand, we first load the relevant function onto our target object

complex = api.Plex4.createExplicitSimplexStream();

and pass the vertices of the complex to it:

complex.addVertex(0);
complex.addVertex(1);
complex.addVertex(2);

In general a complex will have higher simplicies, which by definition are sets of vertices. These are added to the simplicial complex by similarly passing sets to the stream.

complex.addElement([0, 1]);
complex.addElement([0, 2]);
complex.addElement([1, 2]);

Once all simplices have been put into the stream, we close it by calling

complex.finalizeStream();

At this point complex is a simplicial complex that encodes the boundary of a triangle. We can get the number of simplices (of all dimension) contained in the simplicial complex by calling

complex.getSize()

Modular Simplicial Algorithm

For a given simplicial complex [math]X[/math], the function

 api.Plex4.getModularSimplicialAlgorithm(d, p)

provides an algorithm that can calculate the persistence module of homology groups [math]H_i(X,\mathbb{Z}/p\mathbb{Z})[/math] for all [math] i\leq d[/math], together with representatives of the classes [math] [x]\in H_i [/math].

Note: This algorithm is used more generally for filtered complexes as discussed below. Every simplicial complex [math]X[/math] is trivially filtered by [math] \mathcal{F}_t(X) = X [/math] for all [math]t \in \mathbb{R}[/math].

Example: 1-sphere

Continuing our example from above, the homology groups over [math] \mathbb{Z}/2\mathbb{Z}[/math] of complex up to dimension 3 can be extracted via

homology = api.Plex4.getModularSimplicialAlgorithm(3, 2);
persistenceIntervals = homology.computeIntervals(complex)

The output is a number of intervals, that tell us for which values of the filtration parameter a non-trivial homology class exists. If we are also interested in representatives of the non-trivial classes we can use

persistenceAnnotatedIntervals = homology.computeAnnotatedIntervals(complex)

This gives the parameter values of non-trivial classes together with their representatives.

Example: [math]n[/math]-Sphere

The explicit construction above is of course too tiresome for more complicated simplicial complexes. We exemplify which additional methods of simplex stream objects exist, by constructing [math] n[/math]-spheres.

% set dimension and load simplex stream
dimension = 9;
sphere = api.Plex4.createExplicitSimplexStream();

% construct simplicial sphere
stream.addElement(0:(dimension + 1));
stream.ensureAllFaces();
stream.removeElementIfPresent(0:(dimension + 1));
stream.finalizeStream();

% print out the total number of simplices in the complex
stream.getSize()

% get homology algorithm over Z/2Z up to dimension+1
persistence = api.Plex4.getModularSimplicialAlgorithm(dimension + 1, 2);

% compute and print the homology groups
intervals = persistence.computeIntervals(stream)

Examples

We can now use what we've learned above to investigate more complicated data sets.