{"id":20916276,"url":"https://github.com/giotto-ai/giotto-ph","last_synced_at":"2025-10-14T23:06:28.182Z","repository":{"id":43351233,"uuid":"317214052","full_name":"giotto-ai/giotto-ph","owner":"giotto-ai","description":"High performance implementation of Vietoris-Rips persistence.","archived":false,"fork":false,"pushed_at":"2024-05-30T07:58:29.000Z","size":36858,"stargazers_count":46,"open_issues_count":11,"forks_count":13,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-21T12:21:50.489Z","etag":null,"topics":["computational-topology","machine-learning","topological-data-analysis","topology"],"latest_commit_sha":null,"homepage":"https://giotto-ai.github.io/giotto-ph/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giotto-ai.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.rst","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"GOVERNANCE.rst","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-30T12:17:38.000Z","updated_at":"2025-04-19T16:17:56.000Z","dependencies_parsed_at":"2024-03-07T12:11:49.093Z","dependency_job_id":null,"html_url":"https://github.com/giotto-ai/giotto-ph","commit_stats":{"total_commits":183,"total_committers":5,"mean_commits":36.6,"dds":"0.36612021857923494","last_synced_commit":"780f45634461a90203563b76d1c8a905d1bcf0ee"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giotto-ai%2Fgiotto-ph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giotto-ai%2Fgiotto-ph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giotto-ai%2Fgiotto-ph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giotto-ai%2Fgiotto-ph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giotto-ai","download_url":"https://codeload.github.com/giotto-ai/giotto-ph/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253932715,"owners_count":21986441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computational-topology","machine-learning","topological-data-analysis","topology"],"created_at":"2024-11-18T16:21:15.339Z","updated_at":"2025-10-14T23:06:23.160Z","avatar_url":"https://github.com/giotto-ai.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n.. |wheels| image:: https://github.com/giotto-ai/giotto-ph/actions/workflows/wheels.yml/badge.svg\n.. _wheels:\n\n.. |ci| image:: https://github.com/giotto-ai/giotto-ph/actions/workflows/ci.yml/badge.svg\n.. _ci:\n\n.. |docs| image:: https://github.com/giotto-ai/giotto-ph/actions/workflows/deploy-github-pages.yml/badge.svg\n.. _docs:\n\n|wheels|_ |ci|_ |docs|_\n\n=========\ngiotto-ph\n=========\n\n``giotto-ph`` is a high-performance implementation of Vietoris–Rips (VR) persistence on the CPU, and is distributed under the GNU AGPLv3 license.\nIt consists of an improved reimplementation of `Morozov and Nigmetov's \"lock-free Ripser\" \u003chttps://dl.acm.org/doi/10.1145/3350755.3400244\u003e`_\nand in addition makes use of a parallel implementation of the *apparent pairs* optimization used in `Ripser v1.2 \u003chttps://github.com/Ripser/ripser\u003e`_.\nIt also contains an improved reimplementation of `GUDHI's Edge Collapse (EC) algorithm \u003chttps://hal.inria.fr/hal-02395227\u003e`_ and offers support\nfor weighted VR filtrations. See also `Morozov's Ripser fork \u003chttps://github.com/mrzv/ripser/tree/lockfree\u003e`_, Nigmetov's\n`Oineus library \u003chttps://github.com/grey-narn/oineus\u003e`_, and `GUDHI's EC implementation \u003chttp://gudhi.gforge.inria.fr/doc/latest/group__edge__collapse.html\u003e`_.\n\n``giotto-ph`` is part of the `Giotto \u003chttps://github.com/giotto-ai\u003e`_ family of open-source projects and designed for tight integration with\nthe `giotto-tda \u003chttps://github.com/giotto-ai/giotto-tda\u003e`_ and `pyflagser \u003chttps://github.com/giotto-ai/giotto-tda\u003e`_ libraries.\n\n\nProject genesis\n===============\n\n``giotto-ph`` is the result of a collaborative effort between `L2F SA \u003chttps://www.l2f.ch/\u003e`_,\nthe `Laboratory for Topology and Neuroscience \u003chttps://www.epfl.ch/labs/hessbellwald-lab/\u003e`_ at EPFL,\nand the `Institute of Reconfigurable \u0026 Embedded Digital Systems (REDS) \u003chttps://heig-vd.ch/en/research/reds\u003e`_ of HEIG-VD.\n\n\nLicense\n=======\n\n.. _L2F team: business@l2f.ch\n\n``giotto-ph`` is distributed under the AGPLv3 `license \u003chttps://github.com/giotto-ai/giotto-tda/blob/master/LICENSE\u003e`_.\nIf you need a different distribution license, please contact the `L2F team`_.\n\n\nParallel persistent homology backend\n====================================\n\nComputing persistence barcodes of large datasets and in high homology degrees is challenging even on modern hardware. ``giotto-ph``'s persistent homology backend\nis 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.\n\nOn challenging datasets, the scaling is quite favourable as shown in the following figure (for more details, see our paper linked below):\n\n.. image:: https://raw.githubusercontent.com/giotto-ai/giotto-ph/main/docs/images/multithreading_speedup.svg\n   :width: 500px\n   :align: center\n\n\nBasic usage in Python\n=====================\n\nBasic imports:\n\n.. code-block:: python\n    \n    import numpy as np\n    from gph import ripser_parallel\n\nPoint clouds\n------------\n\nPersistence diagram of a random point cloud of 100 points in 3D Euclidean space, up to homology dimension 2, using all available threads:\n\n.. code-block:: python\n\n    pc = np.random.random((100, 3))\n    dgm = ripser_parallel(pc, maxdim=2, n_threads=-1)\n\nDistance matrices and graphs\n----------------------------\n\nYou can also work with distance matrices by passing ``metric=\"precomputed\"``:\n\n.. code-block:: python\n\n    from scipy.spatial.distance import pdist, squareform\n    \n    # A distance matrix\n    dm = squareform(pdist(pc))\n    dgm = ripser_parallel(pc, metric=\"precomputed\", maxdim=2, n_threads=-1)\n\nMore 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:\n\n.. code-block:: python\n\n    # Entries can be negative. The only constraint is that, for every i and j, dm[i, j] ≥ max(dm[i, i], dm[j, j])\n    # With dense input, the lower diagonal is ignored\n    adj_dense = np.random.random((100, 100))\n    np.fill_diagonal(adj_dense, 0)\n    dgm = ripser_parallel(adj_dense, metric=\"precomputed\", maxdim=2, n_threads=-1)\n\nAnd here is a sparse adjacency matrix:\n\n.. code-block:: python\n\n    # See API reference for treatment of entries below the diagonal\n    from scipy.sparse import random\n    adj_sparse = random(100, 100, density=0.1)\n    dgm = ripser_parallel(adj_sparse, metric=\"precomputed\", maxdim=2, n_threads=-1)\n\nEdge Collapser\n--------------\n\nPush the computation to higher homology dimensions and larger point clouds/distance matrices/adjacency matrices using edge collapses:\n\n.. code-block:: python\n\n    dgm_higher = ripser_parallel(pc, maxdim=5, collapse_edges=True, n_threads=-1)\n\n(Note: not all datasets and configurations will benefit from edge collapses. For more details, see our paper below.)\n\nWeighted Rips Filtrations\n-------------------------\n\nUse the ``weights`` and ``weight_params`` parameters to constructed a weighted Rips filtration as defined in `this paper \u003chttps://doi.org/10.1007/978-3-030-43408-3_2\u003e`_. ``weights`` can either be a custom 1D array of vertex weights, or the string ``\"DTM\"`` for distance-to-measure reweighting:\n\n.. code-block:: python\n\n    dgm_dtm = ripser_parallel(pc, weights=\"DTM\", n_threads=-1)\n\n\nDocumentation and Tutorials\n===========================\n\nJupyter notebook tutorials can be found in the `examples folder \u003chttps://github.com/giotto-ai/giotto-ph/blob/main/examples\u003e`_.\nThe API reference can be found at https://giotto-ai.github.io/giotto-ph.\n\n\nInstallation\n============\n\nDependencies\n------------\n\nThe latest stable version of ``giotto-ph`` requires:\n\n- Python (\u003e= 3.7)\n- NumPy (\u003e= 1.19.1)\n- SciPy (\u003e= 1.5.0)\n- scikit-learn (\u003e= 0.23.1)\n\nUser installation\n-----------------\n\nThe simplest way to install ``giotto-ph`` is using ``pip``   ::\n\n    python -m pip install -U giotto-ph\n\nIf necessary, this will also automatically install all the above dependencies. Note: we recommend\nupgrading ``pip`` to a recent version as the above may fail on very old versions.\n\nDeveloper installation\n----------------------\n\nPlease consult the `dedicated page \u003chttps://giotto-ai.github.io/giotto-ph/build/html/installation.html#developer-installation\u003e`_\nfor detailed instructions on how to build ``giotto-ph`` from sources across different platforms.\n\n.. _contributing-section:\n\n\nContributing\n============\n\nWe welcome new contributors of all experience levels. The Giotto community goals are to be helpful, welcoming,\nand effective. To learn more about making a contribution to ``giotto-ph``, please consult `the relevant page\n\u003chttps://giotto-ai.github.io/gtda-docs/latest/contributing/index.html\u003e`_.\n\nTesting\n-------\n\nAfter installation, you can launch the test suite from inside the\nsource directory   ::\n\n    pytest gph\n\n\nImportant links\n===============\n\n- Issue tracker: https://github.com/giotto-ai/giotto-ph/issues\n\n\nCiting giotto-ph\n=================\n\nIf you use ``giotto-ph`` in a scientific publication, we would appreciate citations to the following paper:\n\n   `giotto-ph: A Python Library for High-Performance Computation of Persistent Homology of Vietoris–Rips Filtrations \u003chttps://arxiv.org/abs/2107.05412\u003e`_, Burella Pérez *et al*, arXiv:2107.05412, 2021.\n\nYou can use the following BibTeX entry:\n\n.. code:: bibtex\n\n    @misc{burella2021giottoph,\n          title={giotto-ph: A Python Library for High-Performance Computation of Persistent Homology of Vietoris--Rips Filtrations},\n          author={Julián Burella Pérez and Sydney Hauke and Umberto Lupo and Matteo Caorsi and Alberto Dassatti},\n          year={2021},\n          eprint={2107.05412},\n          archivePrefix={arXiv},\n          primaryClass={cs.CG}\n    }\n\n\nCommunity\n=========\n\ngiotto-ai Slack workspace: https://slack.giotto.ai/\n\nContacts\n========\n\nmaintainers@giotto.ai\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiotto-ai%2Fgiotto-ph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiotto-ai%2Fgiotto-ph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiotto-ai%2Fgiotto-ph/lists"}