edu.stanford.math.plex

Class ExplicitStream

java.lang.Object

edu.stanford.math.plex.SimplexStream

edu.stanford.math.plex.ExplicitStream

All Implemented Interfaces:

java.lang.Iterable<Simplex>, java.util.Iterator<Simplex>

public class ExplicitStream
extends SimplexStream

A ExplicitStream instance is SimplexStream whose elements are given explicitly, along with associated values of a persistence parameter. Instances of ExplicitStream can be edited after creation, unlike other SimplexStream subclasses, and an expected use is to create empty ExplicitStreams and add simplices (and associated persistence parameters) to the stream. Instances of this class exist in two states, open (meaning open for additions) and closed. A stream that is closed can be reopened at any time, but streams that are open cannot be used as arguments to the methods in the Persistence class, iterated over, or have their contents dumped for examination. Further, iterators or dump state created when an ExplicitStream is closed become invalid (and useless) once a stream is reopened. There is no explicit way to open one of these streams -- it happens implicitly when an empty stream is created, and when the stream is edited by adding/removing simplices. You can create an iterator on an open stream, but you can't use the iterator until the stream is closed. Dumping the contents of a stream will close it, as will calling the close() method. There is a verification process which must succeed in order for a close to happen -- if the stream is in an inconsistent state (e.g., missing faces or the persistence parameters of a face exceed that of a simplex), an IllegalStateException will be thrown. It should be possible to catch this exception, fix the problem, and proceed, but it might not work in every case. There is also a verify() method which will safely tell if a close() would succeed, and a verbose version that will print messages about all of the errors found.

Version:

$Id$

See Also:

RipsStream

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ExplicitStream.DComplex A DComplex (for Dimensional Complex) is the set of simplices (and associated persistence parameters) of specified dimension for an ExplicitStream.
protected static class	ExplicitStream.ExplicitStreamIterator Instances provide Iterator for non-destructive iterating over entries.

Nested classes/interfaces inherited from class edu.stanford.math.plex.SimplexStream

SimplexStream.ComparisonType, SimplexStream.Head, SimplexStream.Stack, SimplexStream.Tail

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	closed
protected int	current_dimension
protected int	current_index
protected PlexMessageWindow	message_window
protected int	open_count
protected java.util.HashSet<java.lang.Double>	parameters_table
protected double[]	persistence_parameters
protected java.util.HashMap<Simplex,java.lang.Double>	simplex_table
protected Simplex[][]	simplices

Constructor Summary

Constructors

Constructor and Description
ExplicitStream() Constructor for ExplicitStream.

Method Summary

Methods

Modifier and Type	Method and Description
void	add(double[][] simplex_array, double[] parray) Add an array of simplices, specified by matching vertex vectors and persistence parameters, to the stream.
void	add(double[] vertices, double parameter) Add a simplex, specified by its vertex vector and persistence parameter, to the stream.
void	add(int[][] simplex_array, double[] parray) Add an array of simplices, specified by matching vertex vectors and persistence parameters, to the stream.
void	add(int[] vertices, double parameter) Add a simplex, specified by its vertex vector and persistence parameter, to the stream.
protected void	add(Simplex s, double p)
void	close() Close the stream the current additions, provided that the contents are consistent and complete.
double	convert_filtration_index(int fi) Convert a filtration index into a persistence parameter (i.e., double) -- gets overloaded by some subclasses.
ExplicitStream.DComplex	dump(int dim) Return a DComplex of the requested dimension, if there is one, else null;
static ExplicitStream	enclose(Simplex[][] complex) Convert a Simplex[][] into an ExplicitStream.
void	ensure_all_faces() Make sure all of the faces of simplices in simplex_table are present in the table as well.
protected void	ensure_faces(Simplex s, java.lang.Double P, java.util.HashMap<Simplex,java.lang.Double> pending)
protected int[]	ensure_length(int[] v, int index)
protected boolean	faces_are_consistent(Simplex s, java.lang.Double P, boolean error, boolean print)
boolean	hasNext() Is there a next Simplex in the stream?
java.util.Iterator<Simplex>	iterator() Make an iterator for the stream.
java.util.Iterator<Simplex>	iterator(int d) Make an iterator for the stream elements of fixed dimension.
static ExplicitStream	makeExplicit(SimplexStream str) Convert a SimplexStream into an explicit one.
int	maxDimension() Max dimension of simplices in the stream.
protected void	message(java.lang.String msg)
Simplex	next() Next Simplex in the stream.
protected void	open()
void	prune(double[] vertices) Prune a simplex, specified by an array of double, from the stream.
void	prune(double[][] simplex_array) Prune an array of simplices, specified by double[] vertex vectors, from the stream.
void	prune(int[] vertices) Remove a simplex, specified by its vertex vector, and any simplex that contains it, from the stream.
void	prune(int[][] simplex_array) Prune an array of simplices, specified by vertex vectors, from the stream.
void	remove(double[] vertices) Remove a simplex, specified by its vertex vector as an array of double, from the stream.
void	remove(double[][] simplex_array) Remove an array of simplices, specified by double[] vertex vectors, from the stream.
void	remove(int[] vertices) Remove a simplex, specified by its vertex vector, from the stream.
void	remove(int[][] simplex_array) Remove an array of simplices, specified by vertex vectors, from the stream.
int	size() How many simplices are in the stream?
protected void	skip_to_next_index_pair()
static double[]	toDouble(int[] in)
static double[][]	toDouble(int[][] in)
static int[]	toInt(double[] in)
protected static int[][]	toInt(double[][] in)
boolean	verify() Quietly verify the ExplicitStream.
boolean	verify(boolean verbose) Verify the ExplicitStream.

Methods inherited from class edu.stanford.math.plex.SimplexStream

convertInterval, convertInterval, remove

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

simplices

protected Simplex[][] simplices

persistence_parameters

protected double[] persistence_parameters

message_window

protected PlexMessageWindow message_window

closed

protected boolean closed

current_dimension

protected int current_dimension

current_index

protected int current_index

open_count

protected int open_count

simplex_table

protected java.util.HashMap<Simplex,java.lang.Double> simplex_table

parameters_table

protected java.util.HashSet<java.lang.Double> parameters_table

Constructor Detail

ExplicitStream

public ExplicitStream()

Constructor for ExplicitStream.

Make an empty, open, ExplicitStream.

Method Detail

dump

public ExplicitStream.DComplex dump(int dim)

Return a DComplex of the requested dimension, if there is one, else null;

Parameters:

dim - The dimension of the simplices we want.

Returns:

Return a DComplex if dim >= 0 and <= maxDimension(), else null.

hasNext

public boolean hasNext()

Is there a next Simplex in the stream?

Specified by:

hasNext in interface java.util.Iterator<Simplex>

Specified by:

hasNext in class SimplexStream

Returns:

Return true if the stream is not yet empty.

skip_to_next_index_pair

protected void skip_to_next_index_pair()

next

public Simplex next()

Next Simplex in the stream.

Specified by:

next in interface java.util.Iterator<Simplex>

Specified by:

next in class SimplexStream

Returns:

Return the smallest remaining Simplex instance.

toDouble

public static double[] toDouble(int[] in)

toDouble

public static double[][] toDouble(int[][] in)

toInt

public static int[] toInt(double[] in)

toInt

protected static int[][] toInt(double[][] in)

open

protected void open()

makeExplicit

public static ExplicitStream makeExplicit(SimplexStream str)

Convert a SimplexStream into an explicit one.

Parameters:

str - A SimplexStream instance.

Returns:

An ExplicitStream with equivalent Simplex entries.

remove

public void remove(int[] vertices)

Remove a simplex, specified by its vertex vector, from the stream. If the simplex isn't present, do nothing.

Parameters:

vertices - The vertex array of the Simplex to remove.

prune

public void prune(int[] vertices)

Remove a simplex, specified by its vertex vector, and any simplex that contains it, from the stream. If nothing in the stream contains the simplex, do nothing.

Parameters:

vertices - The vertex array of the Simplex to remove.

remove

public void remove(double[] vertices)

Remove a simplex, specified by its vertex vector as an array of double, from the stream. If the simplex isn't present, do nothing.

Parameters:

vertices - The vertex array of the Simplex to remove, where the vertices are double instead of float -- this may be useful when called from Matlab.

prune

public void prune(double[] vertices)

Prune a simplex, specified by an array of double, from the stream.

Parameters:

vertices - The vertex array of the Simplex to prune, where the vertices are double instead of float -- this may be useful when called from Matlab.

remove

public void remove(int[][] simplex_array)

Remove an array of simplices, specified by vertex vectors, from the stream.

Parameters:

simplex_array - An array of arrays of vertices of the Simplices to remove. from Matlab.

prune

public void prune(int[][] simplex_array)

Prune an array of simplices, specified by vertex vectors, from the stream.

Parameters:

simplex_array - An array of arrays of vertices of the Simplices to prune. from Matlab.

remove

public void remove(double[][] simplex_array)

Remove an array of simplices, specified by double[] vertex vectors, from the stream.

Parameters:

simplex_array - An array of arrays of vertices of the Simplices, given as double[][], to remove. This may be useful when called from Matlab.

prune

public void prune(double[][] simplex_array)

Prune an array of simplices, specified by double[] vertex vectors, from the stream.

Parameters:

simplex_array - An array of arrays of vertices of the Simplices, given as double[][], to prune. This may be useful when called from Matlab.

add

protected void add(Simplex s,
       double p)

add

public void add(int[] vertices,
       double parameter)

Add a simplex, specified by its vertex vector and persistence parameter, to the stream. If the simplex is already present, make sure that the associated persistence parameter is the minimum of the new value and the one already in use.

Parameters:

vertices - The vertex array of the Simplex to add.

parameter - The persistence parameter of the Simplex to add.

add

public void add(double[] vertices,
       double parameter)

Add a simplex, specified by its vertex vector and persistence parameter, to the stream. If the simplex is already present, make sure that the associated persistence parameter is the minimum of the new value and the one already in use.

Parameters:

vertices - The vertex array of the Simplex to add, given as a double[].

parameter - The persistence parameter of the Simplex to add.

add

public void add(int[][] simplex_array,
       double[] parray)

Add an array of simplices, specified by matching vertex vectors and persistence parameters, to the stream.

Parameters:

simplex_array - The array of array of vertices specifying the Simplices to add.

parray - The array of associated persistence parameters.

add

public void add(double[][] simplex_array,
       double[] parray)

Add an array of simplices, specified by matching vertex vectors and persistence parameters, to the stream.

Parameters:

simplex_array - The array of array of vertices specifying the Simplices to add, given as arrays of double[].

parray - The array of associated persistence parameters.

ensure_faces

protected void ensure_faces(Simplex s,
                java.lang.Double P,
                java.util.HashMap<Simplex,java.lang.Double> pending)

ensure_all_faces

public void ensure_all_faces()

Make sure all of the faces of simplices in simplex_table are present in the table as well.

In doing so we use the smallest relevant persistence parameter. This does NOT ensure that the full complex will be consistent, but if it fails, the complex was doomed anyway.

ensure_length

protected int[] ensure_length(int[] v,
                  int index)

message

protected void message(java.lang.String msg)

faces_are_consistent

protected boolean faces_are_consistent(Simplex s,
                           java.lang.Double P,
                           boolean error,
                           boolean print)

verify

public boolean verify()

Quietly verify the ExplicitStream. Any successfully closed stream must be consistent.

Overrides:

verify in class SimplexStream

Returns:

Return true if the stream is consistent, else false.

verify

public boolean verify(boolean verbose)

Verify the ExplicitStream. This is only applied to a stream that has been opened for additions. Any successfully closed stream must be consistent.

Parameters:

verbose - if true print a message for every mistake found.

Returns:

Return true if the stream is consistent, else false.

close

public void close()

Close the stream the current additions, provided that the contents are consistent and complete. Otherwise, throw an error indicating the problem. Note that even if the close is successful, further additions can be made at any time. It isn't obvious that this method needs to be public, but it makes some testing simpler.

size

public int size()

How many simplices are in the stream?

Specified by:

size in class SimplexStream

Returns:

The number of simplices in a closed stream, else 0 if the stream is open.

maxDimension

public int maxDimension()

Max dimension of simplices in the stream.

Specified by:

maxDimension in class SimplexStream

Returns:

Max dimension of simplices in the stream, if closed and non-empty, else -1.

convert_filtration_index

public double convert_filtration_index(int fi)

Convert a filtration index into a persistence parameter (i.e., double) -- gets overloaded by some subclasses.

Overrides:

convert_filtration_index in class SimplexStream

Parameters:

fi - Filtration index to convert.

Returns:

double persistence parameter.

iterator

public java.util.Iterator<Simplex> iterator()

Make an iterator for the stream.

Returns:

Iterator instance for the stream.

See Also:

Iterator

iterator

public java.util.Iterator<Simplex> iterator(int d)

Make an iterator for the stream elements of fixed dimension.

Parameters:

d - dimension of simplices of interest.

Returns:

Iterator instance for the stream.

See Also:

Iterator

enclose

public static ExplicitStream enclose(Simplex[][] complex)

Convert a Simplex[][] into an ExplicitStream.

Parameters:

complex - A Simplex[][] collection of simplices which are believed to a simplicial complex with findex values usable as persistence parameters.

Returns:

An ExplicitStream instance the encloses the Simplex instances.