{"id":19456826,"url":"https://github.com/aidos-lab/neural-k-forms","last_synced_at":"2025-07-20T19:33:36.593Z","repository":{"id":227531076,"uuid":"697187076","full_name":"aidos-lab/neural-k-forms","owner":"aidos-lab","description":"Simplicial Representation Learning with Neural k-Forms","archived":false,"fork":false,"pushed_at":"2024-03-20T08:54:58.000Z","size":339086,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-25T05:36:43.320Z","etag":null,"topics":["geometric-deep-learning","iclr2024","topological-data-analysis","topological-deep-learning"],"latest_commit_sha":null,"homepage":"https://openreview.net/pdf?id=Djw0XhjHZb","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aidos-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-09-27T08:23:36.000Z","updated_at":"2025-03-14T14:57:52.000Z","dependencies_parsed_at":"2024-03-20T09:49:52.592Z","dependency_job_id":"87e1b385-7a20-4edb-bc1a-0e0a8ad7063b","html_url":"https://github.com/aidos-lab/neural-k-forms","commit_stats":null,"previous_names":["aidos-lab/neural-k-forms"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aidos-lab/neural-k-forms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Fneural-k-forms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Fneural-k-forms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Fneural-k-forms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Fneural-k-forms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aidos-lab","download_url":"https://codeload.github.com/aidos-lab/neural-k-forms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidos-lab%2Fneural-k-forms/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266187272,"owners_count":23889952,"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":["geometric-deep-learning","iclr2024","topological-data-analysis","topological-deep-learning"],"created_at":"2024-11-10T17:18:38.563Z","updated_at":"2025-07-20T19:33:36.575Z","avatar_url":"https://github.com/aidos-lab.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simplicial Representation Learning with Neural $k$-Forms \n\n[Kelly Maggs](https://github.com/kmaggs), [Celia Hacker](https://github.com/celiahacker), and [Bastian Rieck](https://github.com/Pseudomanifold)\n\nThis repository contains the code for the paper [*Simplicial\nRepresentation Learning with Neural\nk-Forms*](https://openreview.net/pdf?id=Djw0XhjHZb), presented at ICLR\n2024, the International Conference on Learning Representations.\n\n**Abstract.** Geometric deep learning extends deep learning to incorporate information\nabout the geometry and topology data, especially in complex domains like\ngraphs. Despite the popularity of message passing in this field, it has\nlimitations such as the need for graph rewiring, ambiguity in\ninterpreting data, and over-smoothing. In this paper, we take\na different approach, focusing on leveraging geometric information from\nsimplicial complexes embedded in $\\mathbb{R}^n$ using node coordinates.\nWe use differential $k$-forms in $\\mathbb{R}^n$ to create\nrepresentations of simplices, offering interpretability and geometric\nconsistency without message passing. This approach also enables us to\napply differential geometry tools and achieve universal approximation.\nOur method is efficient, versatile, and applicable to various input\ncomplexes, including graphs, simplicial complexes, and cell complexes.\nIt outperforms existing message passing neural networks in harnessing\ninformation from geometrical graphs with node features serving as\ncoordinates.\n\n\u003cp align=\"center\"\u003e\n   \u003cimg src=\"figures/pipeline.png\" /\u003e\n\u003c/p\u003e\n\nPlease use the following citation for our work:\n\n```bibtex\n@inproceedings{Maggs24a,\n  title         = {Simplicial Representation Learning with Neural $k$-forms},\n  author        = {Kelly Maggs and Celia Hacker and Bastian Rieck},\n  year          = 2024,\n  booktitle     = {International Conference on Learning Representations},\n  url           = {https://openreview.net/forum?id=Djw0XhjHZb},\n}\n```\n\n## Installation with `pip` or `poetry`\n\nWith `poetry install` or `pip install .`, the base packages will be set up.\nHowever, we recommend installing `torch` and `torch-geometric` *manually*, since\ntheir installation procedure differs based on CPU or GPU versions.\n\nFor the CPU versions, this should work:\n\n```\n$ pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu\n$ pip install torch_geometric\n$ pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.0.0+cpu.html\n$ pip install torchmetrics pytorch-lightning\n```\n\n# Experiments and Tutorials\n\nPlease check out several guided tutorial notebooks in the\n[`notebooks`](./notebooks/) folder. The following notebooks\nare available:\n\n- [Synthetic path classification experiments](https://github.com/aidos-lab/neural-k-forms/blob/main/notebooks/synthetic-path-classification.ipynb)\n- [Synthetic surface classification](https://github.com/aidos-lab/neural-k-forms/blob/main/notebooks/synthetic-surface-classification.ipynb)\n- [Visualising eigenvectors of the simplicial $1$-Laplacian operator](https://github.com/aidos-lab/neural-k-forms/blob/main/notebooks/visualising-eigenvectors.ipynb)\n\nWe have also integrated our neural $k$-forms into a simple architecture for\ngraph classification. To run these  experiments, reproducing **Table 1** and\n**Table 2** from the main paper, run the `graphs.py` script or module\nwith an appropriate name:\n\n```\n$ python -m neural_k_forms.graphs --name BZR                # To run our model\n$ python -m neural_k_forms.graphs --name BZR --baseline GCN # To run a baseline\n```\n\n# Architecture\n\nMost of the heavy lifting is done in\n[`chains.py`](https://github.com/aidos-lab/neural-k-forms/blob/main/neural_k_forms/chains.py).\nAs outlined in the paper, the main ingredient is the calculation of the\n*integration matrix*, which is done by the `generate_integration_matrix()`.\nCurrently, this is realised for $1$-forms (vector fields) only, please\nrefer to the tutorials to see examples of how to run this in higher\ndimensions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidos-lab%2Fneural-k-forms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faidos-lab%2Fneural-k-forms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidos-lab%2Fneural-k-forms/lists"}