physarum-labs 0.2.0__tar.gz

physarum_labs-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alvin Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

physarum_labs-0.2.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: physarum-labs
+Version: 0.2.0
+Summary: Differentiable Linear Programming via Physarum dynamics
+Home-page: https://github.com/Physarum-Lab/physarum-labs
+Author: Alvin Chang
+License: MIT
+Project-URL: Homepage, https://github.com/Physarum-Lab/physarum-labs
+Project-URL: Bug Tracker, https://github.com/Physarum-Lab/physarum-labs/issues
+Project-URL: Source, https://github.com/Physarum-Lab/physarum-labs
+Project-URL: Paper (Meng 2021), https://arxiv.org/abs/2004.14539
+Project-URL: Paper (Solé 2025), https://arxiv.org/abs/2511.08531
+Keywords: physarum,slime-mold,linear-programming,optimal-transport,differentiable,variational,bio-inspired,biological-computing,unconventional-computing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.10
+Requires-Dist: numpy>=1.18
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: scipy>=1.7; extra == "dev"
+Requires-Dist: matplotlib>=3.4; extra == "dev"
+Provides-Extra: compare
+Requires-Dist: scipy>=1.7; extra == "compare"
+Requires-Dist: matplotlib>=3.4; extra == "compare"
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# physarum labs
+
+![Physarum Labs — variational programming from biological dynamics](assets/readme_header.png)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-26%2F26%20passing-brightgreen.svg)](tests/)
+[![arXiv](https://img.shields.io/badge/arXiv-2004.14539-b31b1b.svg)](https://arxiv.org/abs/2004.14539)
+
+A clean MIT-licensed PyTorch implementation of Physarum-inspired
+differentiable solvers, unifying four lines of recent research:
+
+1. **Meng, Ravi, Singh (AAAI 2021)** — Differentiable LP layer via Physarum dynamics
+2. **Solé & Pla-Mauri (arXiv Nov 2025)** — Lagrangian variational framework
+3. **Schick et al. (PRX Life 2026)** — Peristaltic mechanism (substrate inspiration)
+4. **Pietak & Levin (iScience 2025)** — Regulatory Network Machine paradigm
+
+## What's here
+
+- **`physarum_labs/lp.py`** — Clean MIT-licensed PyTorch reimplementation of the
+  Physarum-inspired differentiable LP solver. Drop-in replacement for
+  Sinkhorn-based optimal transport layers. **No Magic Leap license** — completely
+  independent of the SuperGlue codebase.
+
+- **`physarum_labs/variational.py`** — End-to-end `VariationalNetworkMachine`
+  combining the LP solver with Solé's Lagrangian framework. Shows how to add
+  transport dissipation, sparsity, and entropy regularization on top of the
+  base solver, and how to learn edge affinities end-to-end.
+
+- **`examples/cvxpy_comparison.py`** — Validates the Physarum solver against
+  `scipy.optimize.linprog` on a range of problem sizes and iteration counts,
+  and produces a convergence plot at `assets/convergence.png`.
+
+## Why this exists
+
+The only public working implementation of Meng 2021 lives inside the
+`yingxin-jia/Superglue-with-Physarum-Dynamics` repository, which inherits
+Magic Leap's **non-commercial academic use only** license. Anyone wanting
+to commercialize Physarum Labs must reimplement — which is what this codebase
+does, cleanly.
+
+## Quick start
+
+### Install via PyPI
+```bash
+pip install physarum-labs
+```
+
+### Install from source
+```bash
+git clone https://github.com/Physarum-Lab/physarum-labs
+cd physarum-labs
+pip install -e ".[dev]"  # includes scipy and matplotlib for benchmarks
+```
+
+### Run the demos
+```bash
+python -m physarum_labs.lp                # LP solver self-test
+python -m physarum_labs.variational       # maze, matching, learning loop
+python examples/cvxpy_comparison.py       # validates against scipy LP solver
+```
+
+### Run the tests
+```bash
+pytest tests/ -v
+```
+
+```python
+import torch
+from physarum_labs import PhysarumLPLayer
+
+# Cost matrix (lower = better match)
+scores = torch.rand(4, 5)
+solver = PhysarumLPLayer(unmatch_score=-1.0, max_iter=20)
+transport_plan, loss = solver(scores)
+
+# transport_plan shape: (5, 6) — augmented with bin for unmatched
+# transport_plan[:-1, :-1] gives the actual matching scores
+```
+
+## The algorithm
+
+Physarum dynamics solve a doubly-stochastic optimal transport problem by
+iteratively updating a flux vector:
+
+```
+x_{k+1} = (1 - h) * x_k + h * W * A^T * p
+```
+
+where `W = diag(x/c)`, `c` is the cost vector, `A` encodes row/column sum
+constraints, and `p` solves `(A W A^T) p = 1`.
+
+This is mathematically equivalent to a steepest-descent on the LP problem
+(see Meng 2021), and to a least-action variational principle (see
+Solé & Pla-Mauri 2025). It's also the same family of dynamics that
+Pietak & Levin use to describe gene regulatory networks as analog computers.
+
+## License
+
+MIT. Use freely, including commercially.
+
+## References
+
+- Meng, Z., Ravi, S. N., & Singh, V. (2021). Physarum Powered Differentiable
+  Linear Programming Layers and Applications. AAAI.
+  arXiv:2004.14539
+
+- Solé, R., & Pla-Mauri, J. (2025). Cognition as least action: the Physarum
+  Lagrangian. arXiv:2511.08531
+
+- Schick, L., et al. (2026). Decision-Making in Light-Trapped Slime Molds
+  Involves Active Mechanical Processes. PRX Life. DOI: 10.1103/rv7g-d9kx
+
+- Pietak, A., & Levin, M. (2025). Harnessing the analog computing power of
+  regulatory networks with the Regulatory Network Machine. iScience.
+  DOI: 10.1016/j.isci.2025.112536
+
+- Bajpai, S., Lucas-DeMott, A., Murugan, N. J., Levin, M., & Kurian, P.
+  (2025). Morphological computational capacity of Physarum polycephalum.
+  arXiv:2510.19976

physarum_labs-0.2.0/README.md

@@ -0,0 +1,120 @@
+# physarum labs
+
+![Physarum Labs — variational programming from biological dynamics](assets/readme_header.png)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-26%2F26%20passing-brightgreen.svg)](tests/)
+[![arXiv](https://img.shields.io/badge/arXiv-2004.14539-b31b1b.svg)](https://arxiv.org/abs/2004.14539)
+
+A clean MIT-licensed PyTorch implementation of Physarum-inspired
+differentiable solvers, unifying four lines of recent research:
+
+1. **Meng, Ravi, Singh (AAAI 2021)** — Differentiable LP layer via Physarum dynamics
+2. **Solé & Pla-Mauri (arXiv Nov 2025)** — Lagrangian variational framework
+3. **Schick et al. (PRX Life 2026)** — Peristaltic mechanism (substrate inspiration)
+4. **Pietak & Levin (iScience 2025)** — Regulatory Network Machine paradigm
+
+## What's here
+
+- **`physarum_labs/lp.py`** — Clean MIT-licensed PyTorch reimplementation of the
+  Physarum-inspired differentiable LP solver. Drop-in replacement for
+  Sinkhorn-based optimal transport layers. **No Magic Leap license** — completely
+  independent of the SuperGlue codebase.
+
+- **`physarum_labs/variational.py`** — End-to-end `VariationalNetworkMachine`
+  combining the LP solver with Solé's Lagrangian framework. Shows how to add
+  transport dissipation, sparsity, and entropy regularization on top of the
+  base solver, and how to learn edge affinities end-to-end.
+
+- **`examples/cvxpy_comparison.py`** — Validates the Physarum solver against
+  `scipy.optimize.linprog` on a range of problem sizes and iteration counts,
+  and produces a convergence plot at `assets/convergence.png`.
+
+## Why this exists
+
+The only public working implementation of Meng 2021 lives inside the
+`yingxin-jia/Superglue-with-Physarum-Dynamics` repository, which inherits
+Magic Leap's **non-commercial academic use only** license. Anyone wanting
+to commercialize Physarum Labs must reimplement — which is what this codebase
+does, cleanly.
+
+## Quick start
+
+### Install via PyPI
+```bash
+pip install physarum-labs
+```
+
+### Install from source
+```bash
+git clone https://github.com/Physarum-Lab/physarum-labs
+cd physarum-labs
+pip install -e ".[dev]"  # includes scipy and matplotlib for benchmarks
+```
+
+### Run the demos
+```bash
+python -m physarum_labs.lp                # LP solver self-test
+python -m physarum_labs.variational       # maze, matching, learning loop
+python examples/cvxpy_comparison.py       # validates against scipy LP solver
+```
+
+### Run the tests
+```bash
+pytest tests/ -v
+```
+
+```python
+import torch
+from physarum_labs import PhysarumLPLayer
+
+# Cost matrix (lower = better match)
+scores = torch.rand(4, 5)
+solver = PhysarumLPLayer(unmatch_score=-1.0, max_iter=20)
+transport_plan, loss = solver(scores)
+
+# transport_plan shape: (5, 6) — augmented with bin for unmatched
+# transport_plan[:-1, :-1] gives the actual matching scores
+```
+
+## The algorithm
+
+Physarum dynamics solve a doubly-stochastic optimal transport problem by
+iteratively updating a flux vector:
+
+```
+x_{k+1} = (1 - h) * x_k + h * W * A^T * p
+```
+
+where `W = diag(x/c)`, `c` is the cost vector, `A` encodes row/column sum
+constraints, and `p` solves `(A W A^T) p = 1`.
+
+This is mathematically equivalent to a steepest-descent on the LP problem
+(see Meng 2021), and to a least-action variational principle (see
+Solé & Pla-Mauri 2025). It's also the same family of dynamics that
+Pietak & Levin use to describe gene regulatory networks as analog computers.
+
+## License
+
+MIT. Use freely, including commercially.
+
+## References
+
+- Meng, Z., Ravi, S. N., & Singh, V. (2021). Physarum Powered Differentiable
+  Linear Programming Layers and Applications. AAAI.
+  arXiv:2004.14539
+
+- Solé, R., & Pla-Mauri, J. (2025). Cognition as least action: the Physarum
+  Lagrangian. arXiv:2511.08531
+
+- Schick, L., et al. (2026). Decision-Making in Light-Trapped Slime Molds
+  Involves Active Mechanical Processes. PRX Life. DOI: 10.1103/rv7g-d9kx
+
+- Pietak, A., & Levin, M. (2025). Harnessing the analog computing power of
+  regulatory networks with the Regulatory Network Machine. iScience.
+  DOI: 10.1016/j.isci.2025.112536
+
+- Bajpai, S., Lucas-DeMott, A., Murugan, N. J., Levin, M., & Kurian, P.
+  (2025). Morphological computational capacity of Physarum polycephalum.
+  arXiv:2510.19976

physarum_labs-0.2.0/physarum_labs/__init__.py

@@ -0,0 +1,35 @@
+"""
+physarum_labs — Differentiable Linear Programming via Physarum dynamics
+=========================================================================
+
+A clean, MIT-licensed PyTorch implementation of Physarum-inspired
+differentiable solvers, unifying four lines of recent research:
+
+  1. Meng, Ravi, Singh (AAAI 2021) — Differentiable LP layer via Physarum dynamics
+  2. Solé & Pla-Mauri (arXiv Nov 2025) — Lagrangian variational framework
+  3. Schick et al. (PRX Life 2026) — Peristaltic mechanism (substrate inspiration)
+  4. Pietak & Levin (iScience 2025) — Regulatory Network Machine paradigm
+
+Public API
+----------
+    from physarum_labs import (
+        PhysarumLPLayer,             # differentiable LP layer
+        VariationalPhysarumSolver,   # LP layer + Lagrangian regularization
+        VariationalNetworkMachine,   # end-to-end graph/transport learner
+    )
+
+License: MIT
+"""
+
+from __future__ import annotations
+
+from physarum_labs.lp import PhysarumLPLayer, VariationalPhysarumSolver
+from physarum_labs.variational import VariationalNetworkMachine
+
+__all__ = [
+    "PhysarumLPLayer",
+    "VariationalPhysarumSolver",
+    "VariationalNetworkMachine",
+]
+
+__version__ = "0.2.0"