pershom

This module exposes the C++/CUDA backend functionality for Python.

Terminology

Descending sorted boundary array:

Boundary array which encodes the boundary matrix (BM) for a given filtration in column first order. Let BA be the descending_sorted_boundary of BM, then BA[i, :] is the i-th column of BM. Content encoded as decreasingly sorted list, embedded into the array with -1 padding from the right.

Example :

BA[3, :] = [2, 0, -1, -1] then \(\partial(v_3) = v_0 + v_2\)

BA[6, :] = [5, 4, 3, -1] then \(\partial(v_6) = v_3 + v_4 + v_5\)

Compressed descending sorted boundary array:

Same as descending sorted boundary array but rows consisting only of -1 are omitted. This is sometimes used for efficiency purposes and is usually accompanied by a vector, v, telling which row of the reduced BA corresponds to which row of the uncompressed BA, i.e., v[3] = 5 means that the 3rd row of the reduced BA corresponds to the 5th row in the uncompressed version.

Birth/Death-time:

Index of the coresponding birth/death event in the filtration. This is always an integer.

Birth/Death-value:

If a filtration is induced by a real-valued function, this corresponds to the value of this function corresponding to the birth/death event. This is always real-valued.

Limitations

Currently all cuda backend functionality only supports int64_t and float32_t typing.

torchph.pershom.pershom_backend.calculate_persistence(compr_desc_sort_ba: torch.Tensor, ba_row_i_to_bm_col_i: torch.Tensor, simplex_dimension: torch.Tensor, max_dim_to_read_of_reduced_ba: int, max_pairs: int = -1) → List[List[torch.Tensor]][source]

Returns the barcodes of the given encoded boundary array.

Parameters

  • compr_desc_sort_ba – A compressed descending sorted boundary array, see readme section top.

  • ba_row_i_to_bm_col_i – Vector whose i-th entry is the column index of the boundary matrix the i-th row in compr_desc_sort_ba corresponds to.

  • simplex_dimension – Vector whose i-th entry is the dimension if the i-th simplex in the given filtration

  • max_pairs – see find_merge_pairings.

  • max_dim_to_read_of_reduced_ba – features up to max_dim_to_read_of_reduced_ba are read from the reduced boundary array.

Returns

List of birth/death times.

ret[0][n] are non essential birth/death-times of dimension n.

ret[1][n] are birth-times of essential classes of dimension n.

torchph.pershom.pershom_backend.find_merge_pairings(pivots: torch.Tensor, max_pairs: int = -1) → torch.Tensor[source]

Finds the pairs which have to be merged in the current iteration of the matrix reduction.

Parameters

  • pivots – The pivots of a descending sorted boundary array. Expected size is Nx1, where N is the number of columns of the underlying descending sorted boundary array.

  • max_pairs – The output is at most a max_pairs x 2 Tensor. If set to default all possible merge pairs are returned.

Returns

The merge pairs, p, for the current iteration of the reduction. p[i] is a merge pair. In boundary matrix notation this would mean column p[i][0] has to be merged into column p[i][1].

torchph.pershom.pershom_backend.merge_columns_(compr_desc_sort_ba: torch.Tensor, merge_pairs: torch.Tensor) → None[source]

Executes the given merging operations inplace on the descending sorted boundary array.

Parameters

  • compr_desc_sort_ba – see module description top.

  • merge_pairs – output of a find_merge_pairings call.

Returns

None

torchph.pershom.pershom_backend.read_barcodes(pivots: torch.Tensor, simplex_dimension: torch.Tensor, max_dim_to_read_of_reduced_ba: int) → List[List[torch.Tensor]][source]

Reads the barcodes using the pivot of a reduced boundary array.

Parameters

  • pivots – pivots is the first column of a compr_desc_sort_ba

  • simplex_dimension – Vector whose i-th entry is the dimension if the i-th simplex in the given filtration.

  • max_dim_to_read_of_reduced_ba – features up to max_dim_to_read_of_reduced_ba are read from the reduced boundary array

Returns

List of birth/death times.

ret[0][n] are non essential birth/death-times of dimension n.

ret[1][n] are birth-times of essential classes of dimension n.

torchph.pershom.pershom_backend.vr_persistence(distance_matrix: torch.Tensor, max_dimension: int, max_ball_diameter: float = 0.0) → List[List[torch.Tensor]][source]

Returns the barcodes of the Vietoris-Rips complex of a given distance matrix.

Note: distance_matrix is assumed to be a square matrix. Practically, symmetry is not required and the upper diagonal part is ignored. For the computation, just the lower diagonal part is used.

Parameters

  • distance_matrix – Distance matrix the Vietoris-Rips complex is based on.

  • max_dimension – The dimension of the used Vietoris-Rips complex.

  • max_ball_diameter – If not 0, edges whose two defining vertices’ distance is greater than max_ball_diameter are ignored.

Returns

List of birth/death times.

ret[0][n] are non essential birth/death-values of dimension n.

ret[1][n] are birth-values of essential classes of dimension n.

torchph.pershom.pershom_backend.vr_persistence_l1(point_cloud: torch.Tensor, max_dimension: int, max_ball_diameter: float = 0.0) → List[List[torch.Tensor]][source]

Returns the barcodes of the Vietoris-Rips complex of a given point cloud w.r.t. the l1 (manhatten) distance.

Parameters

  • point_cloud – Point cloud from which the Vietoris-Rips complex is generated.

  • max_dimension – The dimension of the used Vietoris-Rips complex.

  • max_ball_diameter – If not 0, edges whose two defining vertices’ distance is greater than max_ball_diameter are ignored.

Returns

List of birth/death times.

ret[0][n] are non essential birth/death-values of dimension n.

ret[1][n] are birth-values of essential classes of dimension n.