Package: persuit
persuitPersuit is an experimental persistent homology (PH) library, which aims to speed up your PH pipeline by reducing the boundary matrixwhilstit is being constructed.
The library is written in Rust and Python bindings are provided via PyO3.WarningPersuit is currently in alpha.
The implementation of the standard algorithm is far from optimised, the API is not fixed and no tests have been written.
Use at your own risk.MotivationHere is the rough outline of many PH pipelines:Read in data.Build up a basis for the columns of your boundary matrix.Sort this basis by the filtration time and dimension.Compute a sparse representation of the boundary matrix.Pass the sparse matrix to a PH library (e.g. Eirene or PHAT) to reduce the boundary matrix and hence compute pairings.In many (although not all) pipelines, steps 1-4 takes significantly longer than step 5.
Indeed, often step 4 alone can take longer than step 5.
However, step 5 often still takes a significant time to complete.
In such circumstances, Persuit might offer a speed up.Consider the "standard algorithm" for persistence computation:for each column j:
    while ∃i < j with low(i) = low(j):
        add col[i] to col[j]
    endwhile
endforNote that in order to reduce columnjwe only need the previous columns.
Therefore, we can start reducingjas soon as it is available!
That is, we can compute PHwhilewe compute the sparse boundary matrix and potentially hide some of the cost of the standard algorithm.Main IdeaThe two core functions provided by Persuit arestd_persuitandstd_persuit_collected.
Let's focus onstd_persuit.pubfnstd_persuit<C,T>(col_iterator:T)->StandardAlgo<C,flume::IntoIter<(usize,C)>>whereT:Iterator<Item=C>+Send+'static,C:Column+'static,{let(tx,rx)=flume::unbounded();thread::spawn(move||{letmutenumerated_cols=col_iterator.enumerate();whileletSome(enum_col)=enumerated_cols.next(){tx.send(enum_col).unwrap();}});StandardAlgo::new(rx.into_iter())}Note that the output of this function is an iterator over the pairings computed by the standard algorithm.
Despite all of the annotations, the signature ofstd_persuitis essentiallyiterator over columns -> iterator over paringsThe way this is achieved is:Spawn a new thread and setup a channel for communication.The new thread consumes columns from the input iterator and puts them on the channel.The main thread consumes columns off the channel and performs the standard algorithm on these columns, unaware they are coming from a different thread.Since the new thread is constantly consuming the iterator, we construct the sparse matrix at the usual rate.
Meanwhile, the main thread is reducing columns of this sparse matrix as soon as it can.Currently, due to the overhead of inter-thread communication this is usually slower than the serial algorithm.UsageThe main Python bindings arestd_persuitandstd_persuit_serial.
These functions take one argument: aniteratorover sparse columns.
Currently,persuitonly supports ℤ₂ homology and hence your matrix should also have enties in ℤ₂.
The ith iterate of the provided iterator should be an increasing list of indices of the non-zero rows in the ith column of your boundary matrix.
Seetest.pyfor an illustrative example.TODOTry outFnvHasMap,IndexMapandBTreeMapfor storinglow_inverseTry out linked lists andbitvecas Column typesReturn (Lex-optimal) representativesPython bindingsImplement other PH algorithms, e.g. clear and compress?Implement parallel over dimensions?Write a basic READMEFind example where this actually does speed up PH (need PH computation to be a significant portion of the time)Write tests (unit, integration + property)Benchmark