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 every simplex stream we may 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.