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

Make sure you have 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 for Matlab download the latest release at [1]. Download the zip file containing the Matlab examples, which should be called something like matlab-examples-4.2.2.zip . Unzip the folder to a known location, the resulting folder should be called matlab_examples .

In Matlab, change your current folder to matlab_examples . Then run the script load_javaplex.m and import the JavaPlex routines provided by the package. You can do this for example by entering the following commands into the command line

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

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

To check wether JavaPlex was loaded correctly, 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 $X$, the algorithm api.Plex4.getModularSimplicialAlgorithm(dimension, p) calculates the (persistence module of) homology groups $H_i(X,\mathbb{Z}/p\mathbb{Z})$, $i\leq dimension$ and representatives of the classes $[x]\in H_i$.

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

= 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 $\mathbb{Z}/2\mathbb{Z} 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 $n$-Sphere

The explicit construction above is of course too tiresome for more complicated simplicial complexes. We exemplify additional methods of simplex stream objects to generate $n$-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)

Customization

Examples

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