{"id":17606603,"url":"https://github.com/peekxc/splex","last_synced_at":"2025-03-29T23:16:59.216Z","repository":{"id":69166175,"uuid":"589418370","full_name":"peekxc/splex","owner":"peekxc","description":"Package documentation","archived":false,"fork":false,"pushed_at":"2024-07-18T16:38:13.000Z","size":2552,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-05T00:41:43.232Z","etag":null,"topics":["graph-datastructures","simplicial-complex","topological-data-analysis"],"latest_commit_sha":null,"homepage":"https://peekxc.github.io/splex/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peekxc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2023-01-16T03:56:11.000Z","updated_at":"2024-07-18T16:38:17.000Z","dependencies_parsed_at":"2023-12-05T20:23:04.440Z","dependency_job_id":"5f0fb1a7-6dae-4def-bbbe-3a626d140850","html_url":"https://github.com/peekxc/splex","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peekxc%2Fsplex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peekxc%2Fsplex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peekxc%2Fsplex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peekxc%2Fsplex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peekxc","download_url":"https://codeload.github.com/peekxc/splex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246254148,"owners_count":20747949,"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":["graph-datastructures","simplicial-complex","topological-data-analysis"],"created_at":"2024-10-22T15:45:20.378Z","updated_at":"2025-03-29T23:16:59.198Z","avatar_url":"https://github.com/peekxc.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Tests](https://github.com/peekxc/splex/actions/workflows/package.yml/badge.svg)](https://github.com/peekxc/splex/actions/workflows/package.yml)\n[![coverage_badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/peekxc/ef42349965f40edf4232737026690c5f/raw/coverage_info.json)](https://coveralls.io/github/peekxc/splex)\n[![python_badge](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue)](https://github.com/peekxc/splex/actions/workflows/python-package.yml)\n[![coverage_badge](https://img.shields.io/github/actions/workflow/status/peekxc/splex/build-macos.yml?logo=apple\u0026logoColor=white)](https://github.com/peekxc/splex/actions/workflows/build-macos.yml)\n[![coverage_badge](https://img.shields.io/github/actions/workflow/status/peekxc/splex/build-windows.yml?logo=windows\u0026logoColor=white)](https://github.com/peekxc/splex/actions/workflows/build-windows.yml)\n[![coverage_badge](https://img.shields.io/github/actions/workflow/status/peekxc/splex/build-linux.yml?logo=linux\u0026logoColor=white)](https://github.com/peekxc/splex/actions/workflows/build-linux.yml)\n\n`splex` is a Python package aimed at providing common, _pythonic_ interface for constructing and manipulating [abstract simplicial complexes](https://en.wikipedia.org/wiki/Abstract_simplicial_complex) that is both efficient and representation independent, similar to how [NetworkX](https://networkx.org/documentation/stable/index.html) handles graph data. \n\nLonger term, the goal of `splex` is to provide simple and performant implementations of common operations on complexes in ways that are highly interoperable with the rest of the scientific Python ecosystem (e.g. SciPy, NumPy). \n\nFor example, one objective to provide efficient ways to construct boundary (+Laplacian) [sparse matrices](https://docs.scipy.org/doc/scipy/reference/sparse.html) and [operators](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html) from _any_ simplicial complex. Other operations, such as e.g. random complex generation, geometric realizations, and sparsification algorithms are also planned. \n\n\u003e __NOTE__: `splex` is early-stage software primarily used for research currently, and many common simplicial operations are not yet provided (e.g. simplicial maps, sparsification)---if you’re interested in using `splex` but need some specific functionality, please open an issue.\n\n## Installation \n\n```\npython -m pip install -e git+https://github.com/peekxc/splex.git#egg=splex\n```\n\n## Documentation \n\nDocumentation available [here](https://peekxc.github.io/splex/)\n\n## Quickstart \n\n```python\ns = Simplex([0,1,2])                       # Explicit simplex class for value and set-like semantics\nS = simplicial_complex([[0,1,2], [4,5]])   # Complexes are constructible from myriad of types\nK = filtration(S, weight=lambda s: max(s)) # Filtrations are easy to specify via functions \n\n## All the types are pythonic and easy to use  \nK.print()\nK.add(...)\nK.remove(...)\nK.update(...)\n\n## But also come with specific functionality \nK.reindex(...)\n\n## Complexes are representation-independent..\nS = simplicial_complex(S, form='tree') # convert to tree-based\nS = simplicial_complex(S, form='rank') # convert to array-based\n\n## as are generic functions\nfrom splex.generics import faces, card, dim\nfor s in faces(S):\n  ...\n```\n\nFor more details, see the documentation. \n\n## Motivation \n\nWhat if there was a natural type for representing simplices? \n```python\ns, t = Simplex([0,1,2]),  Simplex([0,1])\n\nprint(s.dim(), \":\", s)\n# 2 : (0,1,2)\n\nt \u003c s, t \u003c= s, s \u003c t\n# True, True, False\n\nt in s.boundary()\n# True \n\nprint(list(s.faces()))\n# [(0), (1), (2), (0,1), (0,2), (1,2), (0,1,2)]\n```\n\nWhat if said type was flexible and easy to work with, supporting no-fuss construction\n\n```python\nSimplex(2) == Simplex([2])                      # value-types are always unboxed \nSimplex([1,2]) == Simplex([1, 2, 2])            # simplices have unique entries, are hashable \nSimplex((1,5,3)) == Simplex(np.array([5,3,1]))  # arrays and tuples supported out of the box \nSimplex((0,1,2)) == Simplex(range(3))           # ... as are generators, iterables, collections, etc\n```\n\nWhat if it was easy to use with other native Python tools?\n```python\ns = Simplex([0,1,3,4])\nnp.array(s)          # native __array__ conversion enabled\nlen(s)               # __len__ is as expected \n3 in s               # __contains__ acts vertex-wise\nlist(iter(s))        # __iter__ also acts vertex-wise\ns[0]                 # __getitem__ as well \ns[0] = 5             # __setitem__ is *not*: Simplices are immutable!\n\n# Which means native support for the expected protocols \nisinstance(s, Sized)     # True \nisinstance(s, Container) # True \nisinstance(s, Iterable)  # True \nisinstance(s, Mapping)   # False \n```\n\nWhat if there was a similar construction for simplicial complexes?\n```python\nS = simplicial_complex([[0,1,2,3], [4,5], [6]])\nprint(S)\n# 3-d complex with (7, 7, 4, 1)-simplices of dimension (0, 1, 2, 3)\n\n[s for s in S.faces()] # [(0), (1), ..., (1,2,3), (0,1,2,3)]\nS.add([5,6]) # adds Simplex([5,6]) to the complex \n```\n\n.. and for filtered complexes as well?\n```python\nK = filtration(enumerate(S)) # index-ordered filtration\nprint(K)\n# 3-d filtered complex with (7, 7, 4, 1)-simplices of dimension (0, 1, 2, 3)\nprint(format(K))\n# 3-d filtered complex with (7, 7, 4, 1)-simplices of dimension (0, 1, 2, 3)\n# I: 0   ≤ 1   ≤ 2   ≤ 3   ≤ 4   ≤  ...  ≤ 17      ≤ 18       \n# S: (0) ⊆ (1) ⊆ (2) ⊆ (3) ⊆ (4) ⊆  ...  ⊆ (1,2,3) ⊆ (0,1,2,3)\n\n[s for s in K.faces()] # [(0), (1), ..., (1,2,3), (0,1,2,3)]\n```\n\nWhat if there were multiple choices in representation...\n\n\n```python\nSS = simplicial_complex([[0,1,2,3]], form=\"set\")  # simplices stored as collections in a set \nST = simplicial_complex([[0,1,2,3]], form=\"tree\") # simplices stored as nodes in a tree \nSR = simplicial_complex([[0,1,2,3]], form=\"rank\") # simplices stored as integers in an array \n# ... \n```\n\n...but every representation was supported through _generics_\n\n\n```python\nfaces(SS)           # calls overloaded .faces()\nfaces(ST)           # same as above, but using a simplex tree\nfaces(SR)           # same as above, but using a rank complex \nfaces([[0,1,2,3]])  # same as above! Falls back to combinations! \n# same goes for .card(), .dim(), .boundary(), ...\n```\n\nWhat if extending support to all such types generically was as easy as\n\n```python\ndef faces(S: ComplexLike) -\u003e Iterator[SimplexConvertible]:\n  if hasattr(S, \"faces\"):\n    yield from S.faces()\n  else:\n    ...\n```\n\n...where `ComplexLike` is a [protocol](https://mypy.readthedocs.io/en/stable/protocols.html) defining a minimal interface needed for Python types to be interpreted as complexes. This is duck typing---no nominal inheritance needed! Just define your type, make it _pythonic_ via abc.collections and go. \n\n\n```python\nfrom typing import *\nfrom splex.meta import SimplexConvertible, ComplexLike \n\nclass MyCellComplex:\n  def __iter__(self) -\u003e Iterator[SimplexConvertible]:\n    ... # \u003c specific implementation \u003e \n```\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeekxc%2Fsplex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeekxc%2Fsplex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeekxc%2Fsplex/lists"}