Package: giotto-ph
giotto-phgiotto-phis a high-performance implementation of Vietoris–Rips (VR) persistence on the CPU, and is distributed under the GNU AGPLv3 license.
It consists of an improved reimplementation ofMorozov and Nigmetov’s “lock-free Ripser”and in addition makes use of a parallel implementation of theapparent pairsoptimization used inRipser v1.2.
It also contains an improved reimplementation ofGUDHI’s Edge Collapse (EC) algorithmand offers support
for weighted VR filtrations. See alsoMorozov’s Ripser fork, Nigmetov’sOineus library, andGUDHI’s EC implementation.giotto-phis part of theGiottofamily of open-source projects and designed for tight integration with
thegiotto-tdaandpyflagserlibraries.Project genesisgiotto-phis the result of a collaborative effort betweenL2F SA,
theLaboratory for Topology and Neuroscienceat EPFL,
and theInstitute of Reconfigurable & Embedded Digital Systems (REDS)of HEIG-VD.Licensegiotto-phis distributed under the AGPLv3license.
If you need a different distribution license, please contact theL2F team.Parallel persistent homology backendComputing persistence barcodes of large datasets and in high homology degrees is challenging even on modern hardware.giotto-ph’s persistent homology backend
is able to distribute the key stages of the computation (namely, search for apparent pairs and coboundary matrix reduction) across an arbitrary number of available CPU threads.On challenging datasets, the scaling is quite favourable as shown in the following figure (for more details, see our paper linked below):Basic usage in PythonBasic imports:importnumpyasnpfromgphimportripser_parallelPoint cloudsPersistence diagram of a random point cloud of 100 points in 3D Euclidean space, up to homology dimension 2, using all available threads:pc=np.random.random((100,3))dgm=ripser_parallel(pc,maxdim=2,n_threads=-1)Distance matrices and graphsYou can also work with distance matrices by passingmetric="precomputed":fromscipy.spatial.distanceimportpdist,squareform# A distance matrixdm=squareform(pdist(pc))dgm=ripser_parallel(pc,metric="precomputed",maxdim=2,n_threads=-1)More generally, you can work with dense or sparse adjacency matrices of weighted graphs. Here is a dense square matrix interpreted as the adjacency matrix of a fully connected weighted graph with 100 vertices:# Entries can be negative. The only constraint is that, for every i and j, dm[i, j] ≥ max(dm[i, i], dm[j, j])# With dense input, the lower diagonal is ignoredadj_dense=np.random.random((100,100))np.fill_diagonal(adj_dense,0)dgm=ripser_parallel(adj_dense,metric="precomputed",maxdim=2,n_threads=-1)And here is a sparse adjacency matrix:# See API reference for treatment of entries below the diagonalfromscipy.sparseimportrandomadj_sparse=random(100,100,density=0.1)dgm=ripser_parallel(adj_sparse,metric="precomputed",maxdim=2,n_threads=-1)Edge CollapserPush the computation to higher homology dimensions and larger point clouds/distance matrices/adjacency matrices using edge collapses:dgm_higher=ripser_parallel(pc,maxdim=5,collapse_edges=True,n_threads=-1)(Note: not all datasets and configurations will benefit from edge collapses. For more details, see our paper below.)Weighted Rips FiltrationsUse theweightsandweight_paramsparameters to constructed a weighted Rips filtration as defined inthis paper.weightscan either be a custom 1D array of vertex weights, or the string"DTM"for distance-to-measure reweighting:dgm_dtm=ripser_parallel(pc,weights="DTM",n_threads=-1)Documentation and TutorialsJupyter notebook tutorials can be found in theexamples folder.
The API reference can be found athttps://giotto-ai.github.io/giotto-ph.InstallationDependenciesThe latest stable version ofgiotto-phrequires:Python (>= 3.6)NumPy (>= 1.19.1)SciPy (>= 1.5.0)scikit-learn (>= 0.23.1)User installationThe simplest way to installgiotto-phis usingpippython -m pip install -U giotto-phIf necessary, this will also automatically install all the above dependencies. Note: we recommend
upgradingpipto a recent version as the above may fail on very old versions.Developer installationPlease consult thededicated pagefor detailed instructions on how to buildgiotto-phfrom sources across different platforms.ContributingWe welcome new contributors of all experience levels. The Giotto community goals are to be helpful, welcoming,
and effective. To learn more about making a contribution togiotto-ph, please consultthe relevant page.TestingAfter installation, you can launch the test suite from inside the
source directorypytest gphImportant linksIssue tracker:https://github.com/giotto-ai/giotto-ph/issuesCiting giotto-phIf you usegiotto-phin a scientific publication, we would appreciate citations to the following paper:giotto-ph: A Python Library for High-Performance Computation of Persistent Homology of Vietoris–Rips Filtrations, Burella Pérezet al, arXiv:2107.05412, 2021.You can use the following BibTeX entry:@misc{burella2021giottoph,title={giotto-ph: A Python Library for High-Performance Computation of Persistent Homology of Vietoris--Rips Filtrations},author={Julián Burella Pérez and Sydney Hauke and Umberto Lupo and Matteo Caorsi and Alberto Dassatti},year={2021},eprint={2107.05412},archivePrefix={arXiv},primaryClass={cs.CG}}Communitygiotto-ai Slack workspace:https://slack.giotto.ai/Contactsmaintainers@giotto.ai