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.2.2.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(). Furthermore, for a given simplicial complex [math] X[/math], the algorithm api.Plex4.getModularSimplicialAlgorithm(dimension, p) calculates the (persistence module of) homology groups [math] H_i(X,\mathbb{Z}/p\mathbb{Z}), i\leq \text{dimension}[/math] and representatives of the classes [math] [x]\in H_i [/math].

In the following we will use these functions to create a simplicial complex that corresponds to spheres [math] S^1[/math] and [math] S^n[/math] and find the homology groups [math] H_i(X,\mathbb{Z}/2\mathbb{Z})[/math].

Implementing the one-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()

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)

Note: The Modular Simplicial Algorithm automatically interprets our complex as a filtered complex

If we are also interested in representatives of the non-trivial classes we can use

persistenceAnnotatedIntervals = homology.computeAnnotatedIntervals(complex)

and get the parameter values of non-trivial classes together with their representatives.

Implementing the [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.