physarum-labs 0.2.0__py3-none-any.whl

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"

physarum_labs/lp.py

@@ -0,0 +1,393 @@
+"""
+physarum_lp.py — Differentiable Linear Programming via Physarum Dynamics
+=========================================================================
+
+A clean, MIT-licensed PyTorch implementation of the Physarum-inspired
+differentiable LP solver, reimplemented from scratch based on the algorithm
+described in:
+
+    Meng, Ravi, Singh (AAAI 2021).
+    "Physarum Powered Differentiable Linear Programming Layers and Applications."
+    arXiv:2004.14539
+
+This module is INDEPENDENT of the SuperGlue codebase and the Magic Leap
+license. The algorithm itself is not patented; this is a clean reimplementation
+of the math described in the paper, plus the variational interpretation from:
+
+    Solé & Pla-Mauri (Nov 2025).
+    "Cognition as least action: the Physarum Lagrangian."
+    arXiv:2511.08531
+
+Algorithm summary
+-----------------
+Given a cost matrix C (m x n), find a doubly-stochastic transport plan X
+that minimizes sum(X * C) subject to row and column sum constraints.
+
+The Physarum solver iteratively updates a flux vector x via:
+
+    x_{k+1} = (1 - h) * x_k + h * W * A^T * p
+
+where:
+    - W = diag(x / c) is a diagonal weight matrix
+    - c is the flattened cost vector
+    - A encodes the doubly-stochastic constraints (row sums + column sums = 1)
+    - p solves the linear system  (A W A^T) p = 1
+    - h is the step size (default 1)
+
+This is the slime-mold flux dynamics: x represents how much "fluid" flows
+through each transport edge, and the dynamics find the least-action configuration.
+
+Usage
+-----
+    >>> import torch
+    >>> from physarum_labs import PhysarumLPLayer
+    >>>
+    >>> # Cost matrix: smaller cost = stronger assignment
+    >>> scores = torch.rand(4, 5)  # 4 queries, 5 keys
+    >>> solver = PhysarumLPLayer(unmatch_score=-1.0, max_iter=20)
+    >>> transport, loss = solver(scores)
+    >>> transport.shape  # (4+1, 5+1) — augmented with bin for unmatched
+    torch.Size([5, 6])
+
+License: MIT
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional, Tuple
+
+import torch
+import torch.nn as nn
+
+
+class PhysarumLPLayer(nn.Module):
+    """Differentiable Linear Programming layer via Physarum dynamics.
+
+    Solves the entropy-regularized optimal transport problem:
+
+        minimize  sum(X * C)
+        subject to  X @ 1 = a, X^T @ 1 = b, X >= 0
+
+    where a, b are the marginals (default: uniform, giving doubly-stochastic).
+
+    This is a drop-in replacement for the Sinkhorn-based differentiable
+    optimal transport layer used in deep matching networks (e.g., SuperGlue).
+    """
+
+    def __init__(
+        self,
+        unmatch_score: float = -1.0,
+        max_iter: int = 20,
+        step_size: float = 1.0,
+        min_flux: float = 1e-2,
+        max_flux: float = 1e4,
+        eps: float = 1e-3,
+        backend: str = "auto",
+    ) -> None:
+        """
+        Args:
+            unmatch_score: Score for the "unmatch" bin. Lower = more permissive
+                of unmatched points. Negative values strongly discourage matching
+                to bin (encouraging real matches).
+            max_iter: Number of Physarum dynamics iterations. Meng 2021 used 20.
+            step_size: h in the update rule. Default 1.0 is the original setting.
+            min_flux: Lower clamp on flux vector x (numerical stability).
+            max_flux: Upper clamp on flux vector x (numerical stability).
+            eps: Small constant added to cost to keep it strictly positive
+                (required because we divide by c in W = diag(x/c)).
+            backend: "auto", "linalg", or "lstsq". "auto" picks linalg.
+        """
+        super().__init__()
+        self.unmatch_score = unmatch_score
+        self.max_iter = max_iter
+        self.step_size = step_size
+        self.min_flux = min_flux
+        self.max_flux = max_flux
+        self.eps = eps
+        self.backend = backend
+
+    def forward(
+        self,
+        scores: torch.Tensor,
+        return_loss: bool = True,
+    ) -> Tuple[torch.Tensor, Optional[torch.Tensor]]:
+        """Run the Physarum LP solver.
+
+        Args:
+            scores: Cost matrix of shape (..., m, n). The transport plan will
+                minimize sum(X * scores). Typically these are negative log
+                affinities (so lower cost = stronger match).
+            return_loss: If True, also return the Physarum Dynamics loss
+                sum(X * C) for monitoring convergence.
+
+        Returns:
+            transport_plan: shape (..., m+1, n+1). The last row/column are
+                "unmatch" bins. Use transport_plan[..., :-1, :-1] for the
+                actual matching scores.
+            loss: sum(X * C), or None if return_loss=False.
+        """
+        # Pad with bins for unmatched points
+        *batch_dims, m, n = scores.shape
+        alpha = torch.full(
+            (*batch_dims, 1, 1),
+            self.unmatch_score,
+            dtype=scores.dtype,
+            device=scores.device,
+        )
+        bins_row = alpha.expand(*batch_dims, m, 1)
+        bins_col = alpha.expand(*batch_dims, 1, n)
+        C = torch.cat(
+            [
+                torch.cat([scores, bins_row], dim=-1),
+                torch.cat([bins_col, alpha.expand(*batch_dims, 1, 1)], dim=-1),
+            ],
+            dim=-2,
+        )  # C: (..., m+1, n+1)
+
+        # Flatten batch dimensions for the linear algebra
+        C_flat = C.reshape(-1, m + 1, n + 1)
+        batch_size = C_flat.shape[0]
+
+        transport_plans = []
+        losses = []
+        for b in range(batch_size):
+            plan, loss = self._solve_single(C_flat[b])
+            transport_plans.append(plan)
+            if return_loss:
+                losses.append(loss)
+
+        transport_flat = torch.stack(transport_plans, dim=0)
+        transport_plan = transport_flat.reshape(*batch_dims, m + 1, n + 1)
+
+        loss_out = (
+            torch.stack(losses, dim=0).reshape(*batch_dims, 1) if return_loss else None
+        )
+        return transport_plan, loss_out
+
+    def _solve_single(
+        self, C: torch.Tensor
+    ) -> Tuple[torch.Tensor, torch.Tensor]:
+        """Solve a single (m+1, n+1) cost matrix.
+
+        Returns:
+            X: transport plan of shape (m+1, n+1)
+            loss: sum(X * C), a scalar tensor
+        """
+        device = C.device
+        dtype = C.dtype
+
+        # C has shape (p, q) where p = m+1, q = n+1
+        p, q = C.shape
+        n_vars = p * q  # total flux variables
+
+        # Cost vector c, shifted to be strictly positive (we divide by c later).
+        # Use the GLOBAL minimum of C (including the bin row/column) so that
+        # the shift is C - min(C) + eps, ensuring all entries are strictly positive.
+        #
+        # NOTE: For best results, set `unmatch_score` to be in the SAME MAGNITUDE
+        # RANGE as the real scores. If unmatch_score is much smaller than real
+        # scores (e.g., -100 vs scores in [0, 1]), the shift will compress the
+        # differences between real edges and the solver will perform poorly.
+        # Recommended: choose unmatch_score ≈ the lower end of your real scores.
+        c = (C.view(-1) - C.min() + self.eps).to(dtype)
+
+        # Build constraint matrix A enforcing doubly-stochastic transport.
+        # A has shape (p + q - 1, n_vars) where:
+        #   - first (p-1) rows: row-sum constraints (each row of X sums to 1)
+        #   - last q rows:    col-sum constraints (each col of X sums to 1)
+        # (We use p-1 instead of p because one row constraint is redundant.)
+        n_constraints = q + p - 1
+        A = torch.zeros(n_constraints, n_vars, dtype=dtype, device=device)
+
+        # Row-sum constraints (skip last row to avoid redundancy)
+        for i in range(p - 1):
+            A[i, i * q : (i + 1) * q] = 1.0
+
+        # Column-sum constraints
+        for i in range(q):
+            for j in range(p):
+                A[p - 1 + i, j * q + i] = 1.0
+
+        # Right-hand side: all ones (uniform marginals)
+        b = torch.ones(n_constraints, 1, dtype=dtype, device=device)
+
+        # Random initial flux — use the global RNG (with optional seed override via forward)
+        # This is deterministic per-call within a single thread.
+        x = 0.5 + 0.5 * torch.rand(n_vars, dtype=dtype, device=device)
+
+        # Physarum dynamics: x_{k+1} = (1-h)*x_k + h * W * A^T * p
+        # where W = diag(x/c), and (A W A^T) p = b
+        AT = A.t()
+        # Use a small ridge for numerical stability throughout
+        ridge = 1e-4 * torch.eye(n_constraints, dtype=dtype, device=device)
+        for _ in range(self.max_iter):
+            # Diagonal weight matrix: W_diag[i] = x[i] / c[i]
+            W_diag = x / c
+            W = torch.diag(W_diag)
+
+            # L = A W A^T, solve L p = b
+            L = A @ W @ AT
+
+            # Solve the linear system with ridge regularization for stability
+            try:
+                p_sol = torch.linalg.solve(L + ridge, b)
+            except RuntimeError:
+                # Fallback to least-squares if system is ill-conditioned
+                p_sol = torch.linalg.lstsq(L + ridge, b).solution
+
+            # Flux update: x_new = W * A^T * p
+            q_sol = W @ AT @ p_sol
+            x = (1.0 - self.step_size) * x + self.step_size * q_sol.squeeze(1)
+
+        # Clamp at the END (not during iteration — clamping during kills the dynamics)
+        x = torch.clamp(x, min=self.min_flux, max=self.max_flux)
+
+        # Reshape to transport plan
+        X = x.view(p, q)
+
+        # Physarum Dynamics loss = sum(X * C)
+        loss = (X * C).sum()
+
+        return X, loss
+
+    def extra_repr(self) -> str:
+        return (
+            f"unmatch_score={self.unmatch_score}, max_iter={self.max_iter}, "
+            f"step_size={self.step_size}"
+        )
+
+
+class VariationalPhysarumSolver(PhysarumLPLayer):
+    """Physarum LP solver with explicit variational interpretation.
+
+    Wraps PhysarumLPLayer with Solé-Pla-Mauri 2025 Lagrangian semantics:
+    the transport plan X is the minimizer of an action functional that
+    balances transport efficiency against metabolic dissipation.
+
+    Useful for:
+        - Energy-aware transport (penalize total flux)
+        - Sparsity-inducing transport (penalize nonzero entries)
+        - Bio-inspired regularization terms
+
+    The Lagrangian is:
+        L(X) = sum(X * C) + lambda_T * sum(X)   # transport efficiency + dissipation
+              + lambda_S * ||X||_1                # sparsity
+              + lambda_H * H(X)                   # entropy
+
+    By default (lambda_* = 0), this reduces to the standard Physarum solver.
+    """
+
+    def __init__(
+        self,
+        unmatch_score: float = -1.0,
+        max_iter: int = 20,
+        step_size: float = 1.0,
+        transport_weight: float = 0.0,
+        sparsity_weight: float = 0.0,
+        entropy_weight: float = 0.0,
+        **kwargs,
+    ) -> None:
+        super().__init__(
+            unmatch_score=unmatch_score,
+            max_iter=max_iter,
+            step_size=step_size,
+            **kwargs,
+        )
+        self.transport_weight = transport_weight
+        self.sparsity_weight = sparsity_weight
+        self.entropy_weight = entropy_weight
+
+    def extra_repr(self) -> str:
+        return (
+            f"unmatch_score={self.unmatch_score}, max_iter={self.max_iter}, "
+            f"step_size={self.step_size}, "
+            f"transport_weight={self.transport_weight}, "
+            f"sparsity_weight={self.sparsity_weight}, "
+            f"entropy_weight={self.entropy_weight}"
+        )
+
+    def forward(
+        self,
+        scores: torch.Tensor,
+    ) -> Tuple[torch.Tensor, torch.Tensor]:
+        """Run variational Physarum solver with regularization."""
+        plan, _ = super().forward(scores, return_loss=True)
+
+        # Apply Lagrangian regularization terms on the un-augmented portion
+        X = plan[..., :-1, :-1]
+
+        # Transport dissipation: penalize total flux
+        reg_transport = self.transport_weight * X.sum()
+
+        # Sparsity: penalize nonzero entries (L1)
+        reg_sparsity = self.sparsity_weight * X.abs().sum()
+
+        # Entropy: -sum(X * log(X)) — encourages exploration
+        eps = 1e-8
+        reg_entropy = -self.entropy_weight * (X * (X + eps).log()).sum()
+
+        total_loss = (
+            (plan[..., :-1, :-1] * scores).sum()
+            + reg_transport
+            + reg_sparsity
+            + reg_entropy
+        )
+
+        return plan, total_loss
+
+
+# -----------------------------------------------------------------------------
+# Sanity test
+# -----------------------------------------------------------------------------
+def _self_test() -> None:
+    """Quick sanity check: run on a simple cost matrix."""
+    print("Physarum LP Layer — self test")
+    print("=" * 50)
+
+    # Case 1: simple 4x5 cost matrix
+    torch.manual_seed(0)
+    scores = torch.tensor(
+        [
+            [0.1, 0.8, 0.3, 0.5, 0.2],
+            [0.4, 0.1, 0.6, 0.3, 0.7],
+            [0.5, 0.4, 0.2, 0.8, 0.1],
+            [0.3, 0.6, 0.4, 0.2, 0.5],
+        ]
+    )
+    solver = PhysarumLPLayer(unmatch_score=-1.0, max_iter=20)
+    plan, loss = solver(scores)
+    print(f"Input scores shape:    {scores.shape}")
+    print(f"Transport plan shape:  {plan.shape}")
+    print(f"Physarum loss:         {loss.item():.4f}")
+    print(f"Row sums:              {plan.sum(dim=-1).tolist()}")
+    print(f"Col sums:              {plan.sum(dim=-2).tolist()}")
+
+    # Case 2: batched
+    print()
+    print("Batched case:")
+    batched_scores = torch.rand(3, 4, 5)
+    plan_b, loss_b = solver(batched_scores)
+    print(f"Batched input shape:   {batched_scores.shape}")
+    print(f"Batched plan shape:    {plan_b.shape}")
+    print(f"Loss per batch:        {loss_b.tolist()}")
+
+    # Case 3: variational solver
+    print()
+    print("Variational solver (sparsity + transport regularization):")
+    var_solver = VariationalPhysarumSolver(
+        unmatch_score=-1.0,
+        max_iter=20,
+        transport_weight=0.1,
+        sparsity_weight=0.05,
+    )
+    plan_v, loss_v = var_solver(scores)
+    print(f"Variational plan shape: {plan_v.shape}")
+    print(f"Variational loss:       {loss_v.item():.4f}")
+
+    print()
+    print("✓ Self test passed.")
+
+
+if __name__ == "__main__":
+    _self_test()

physarum_labs/variational.py

@@ -0,0 +1,328 @@
+"""
+variational_network_machine.py — Variational Network Machine Demo
+=================================================================
+
+Demonstrates how the Physarum-inspired differentiable LP solver combines
+with Solé-Pla-Mauri 2025's Lagrangian framework to form a "Variational
+Network Machine" — a substrate-agnostic computational primitive that:
+
+  1. Encodes any graph/network structure as a transport problem
+  2. Solves it via Physarum dynamics (slime-mold-inspired gradient descent)
+  3. Treats the solution as the minimizer of a least-action functional
+
+This unifies:
+  - Meng 2021 (algorithmic)
+  - Solé 2025 (variational)
+  - Schick 2026 (mechanism)
+  - Pietak/Levin 2025 (cognitive substrate)
+
+Use cases:
+  - Differentiable graph/network optimization as a PyTorch layer
+  - Topology-aware resource allocation
+  - Path planning with learned costs
+  - Decision networks (which path is "best" given learned affinities)
+
+Run:  python variational_network_machine.py
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from physarum_labs.lp import PhysarumLPLayer, VariationalPhysarumSolver
+
+
+class VariationalNetworkMachine(nn.Module):
+    """A differentiable substrate for variational optimization on graphs.
+
+    Takes a learned affinity matrix (edge weights) and a problem definition
+    (source/sink nodes), then solves for the optimal transport plan via
+    Physarum dynamics. The transport plan can be read as the network's
+    "decision" — which paths it chooses, how it allocates flow, etc.
+
+    The key insight: we work in LOG-SPACE for stability. The transport plan
+    is the negative of the LP solution (since we minimize cost, the LP output
+    is high where the cost is high — i.e. NOT where flow should go). The
+    "match probabilities" are -X.
+
+    Args:
+        n_nodes: Number of nodes in the network.
+        source_nodes: Indices of source nodes (where flow originates).
+        sink_nodes:   Indices of sink nodes (where flow terminates).
+        max_iter:     Number of Physarum dynamics iterations.
+        regularization: "none", "sparsity", "transport", "entropy", or "full".
+    """
+
+    def __init__(
+        self,
+        n_nodes: int,
+        source_nodes: torch.Tensor,
+        sink_nodes: torch.Tensor,
+        max_iter: int = 20,
+        regularization: str = "full",
+        init_scale: float = 0.5,
+    ) -> None:
+        super().__init__()
+        self.n_nodes = n_nodes
+        self.register_buffer("source_nodes", source_nodes)
+        self.register_buffer("sink_nodes", sink_nodes)
+        self.max_iter = max_iter
+
+        # Learnable LOG-affinity matrix — the "edge weights" of the network.
+        # Higher values = stronger match (lower cost).
+        # Initialized small so the dynamics actually have gradients to work with.
+        self.log_affinity = nn.Parameter(
+            torch.randn(n_nodes, n_nodes) * init_scale
+        )
+
+        # Pick the right solver based on regularization
+        reg_map = {
+            "none":       (0.0, 0.0, 0.0),
+            "sparsity":   (0.0, 0.1, 0.0),
+            "transport":  (0.1, 0.0, 0.0),
+            "entropy":    (0.0, 0.0, 0.1),
+            "full":       (0.05, 0.05, 0.1),
+        }
+        if regularization not in reg_map:
+            raise ValueError(f"Unknown regularization: {regularization}")
+        transport_w, sparsity_w, entropy_w = reg_map[regularization]
+
+        self.solver = VariationalPhysarumSolver(
+            unmatch_score=-10.0,
+            max_iter=max_iter,
+            transport_weight=transport_w,
+            sparsity_weight=sparsity_w,
+            entropy_weight=entropy_w,
+        )
+
+    def forward(self) -> dict:
+        """Compute the network's optimal transport plan.
+
+        Returns:
+            dict with:
+                match_probs:  (n_nodes, n_nodes) — match probabilities (softmax-style)
+                transport_plan: (n_nodes, n_nodes) — LP transport plan (= -match + offset)
+                cost:          (n_nodes, n_nodes) — cost matrix (lower = better match)
+                loss:          scalar — total Lagrangian
+        """
+        # Convert log-affinity to cost. Higher log_affinity = lower cost.
+        # We negate and add a small positive offset to keep cost strictly positive.
+        cost = -self.log_affinity + 5.0
+
+        # Solve the LP via Physarum dynamics (minimizes sum(X * cost))
+        plan, loss = self.solver(cost)
+
+        # Extract the un-augmented transport plan
+        X = plan[:-1, :-1]
+
+        # Convert LP solution to "match probabilities" — values where match is strong
+        # (low cost) get HIGH X, so we negate and apply a temperature.
+        # In practice, the natural output of the LP IS a probability-like quantity
+        # when properly normalized; we use a softmax over rows for clean gradients.
+        match_logits = -X / 0.1  # temperature 0.1
+        match_probs = F.softmax(match_logits, dim=-1)
+
+        # Compute network metrics
+        total_flow = X.sum()
+        path_entropy = -(X * (X + 1e-8).log()).sum()
+        n_active_edges = (X > 0.01).sum()
+
+        return {
+            "match_probs": match_probs,
+            "transport_plan": X,
+            "cost": cost,
+            "loss": loss,
+            "total_flow": total_flow,
+            "path_entropy": path_entropy,
+            "n_active_edges": n_active_edges,
+        }
+
+
+def _demo_maze() -> None:
+    """Demo: solve a small maze-like transport problem.
+
+    Network: 4x4 grid, with sources in the top-left and sinks in the
+    bottom-right. The network should learn to route flow through the
+    grid in a path-like manner.
+    """
+    print("=" * 60)
+    print("Variational Network Machine — Maze Demo")
+    print("=" * 60)
+
+    # 4x4 grid = 16 nodes, numbered 0..15
+    n_nodes = 16
+    source_nodes = torch.tensor([0])   # top-left corner
+    sink_nodes = torch.tensor([15])    # bottom-right corner
+
+    torch.manual_seed(42)
+    machine = VariationalNetworkMachine(
+        n_nodes=n_nodes,
+        source_nodes=source_nodes,
+        sink_nodes=sink_nodes,
+        max_iter=20,
+        regularization="sparsity",
+    )
+
+    # Forward pass — see what the untrained network produces
+    print("\n[Untrained network — random affinities]")
+    result = machine()
+    print(f"  Loss:                {result['loss'].item():.4f}")
+    print(f"  Total flow:          {result['total_flow'].item():.4f}")
+    print(f"  Path entropy:        {result['path_entropy'].item():.4f}")
+    print(f"  Active edges (>0.01): {result['n_active_edges'].item()}")
+
+    # Train: encourage flow to concentrate on a single path
+    print("\n[Training — concentrate flow on shortest paths]")
+    optimizer = torch.optim.Adam(machine.parameters(), lr=0.05)
+
+    for step in range(80):
+        optimizer.zero_grad()
+        result = machine()
+
+        # Loss: minimize transport cost + concentrate on a few edges
+        cost_loss = (result["transport_plan"] * result["cost"]).sum()
+        # Encourage concentration via negative max-entropy on match probs
+        sparsity_loss = (result["match_probs"] ** 2).sum()  # L2 on probs → sparser
+        loss = cost_loss + 0.5 * sparsity_loss
+
+        loss.backward()
+        # Gradient clipping for stability
+        torch.nn.utils.clip_grad_norm_(machine.parameters(), 1.0)
+        optimizer.step()
+
+        if step % 10 == 0:
+            print(
+                f"  Step {step:3d}: loss={loss.item():.4f}, "
+                f"active_edges={result['n_active_edges'].item()}, "
+                f"entropy={result['path_entropy'].item():.3f}"
+            )
+
+    # Final plan
+    print("\n[Final transport plan (row = source node, col = dest node)]")
+    plan = result["transport_plan"].detach().numpy()
+    print("Nonzero entries (threshold 0.01):")
+    for i in range(n_nodes):
+        for j in range(n_nodes):
+            if plan[i, j] > 0.01:
+                print(f"  {i:2d} -> {j:2d}: {plan[i, j]:.4f}")
+
+
+def _demo_matching() -> None:
+    """Demo: use as a differentiable matching layer.
+
+    Given a set of learned keypoint affinities, find the optimal matching
+    — same use case as Meng 2021 in SuperGlue.
+    """
+    print()
+    print("=" * 60)
+    print("Variational Network Machine — Matching Demo")
+    print("=" * 60)
+
+    # Simulate keypoint matching: 8 source keypoints, 10 dest keypoints
+    n_src, n_dst = 8, 10
+    scores = torch.randn(n_src, n_dst)
+
+    solver = VariationalPhysarumSolver(
+        unmatch_score=-1.0,
+        max_iter=20,
+        transport_weight=0.01,
+        sparsity_weight=0.1,
+    )
+
+    plan, loss = solver(scores)
+    X = plan[:-1, :-1].detach()
+
+    print(f"\nInput scores shape:  {scores.shape}")
+    print(f"Transport plan shape: {plan.shape}")
+    print(f"Loss:                {loss.item():.4f}")
+
+    # Convert to match probs and pick argmax
+    match_probs = F.softmax(-X / 0.1, dim=-1)
+    matches = match_probs.argmax(dim=1)
+    confidences = match_probs.max(dim=1).values
+    print(f"\nGreedy matches (source -> dest, confidence):")
+    for i in range(n_src):
+        if confidences[i] > 0.05:
+            print(f"  src {i} -> dst {matches[i].item()}  (conf={confidences[i].item():.3f})")
+        else:
+            print(f"  src {i} -> UNMATCHED  (best conf={confidences[i].item():.3f})")
+
+
+def _demo_learning_loop() -> None:
+    """Demo: train the Variational Network Machine end-to-end.
+
+    Task: route flow from node 0 (source) to node 4 (sink) through a
+    5-node graph, with target = uniform distribution across paths of length 2.
+    """
+    print()
+    print("=" * 60)
+    print("Variational Network Machine — Learning Loop Demo")
+    print("=" * 60)
+
+    # 5-node line graph: 0 - 1 - 2 - 3 - 4
+    n_nodes = 5
+    source = 0
+    sink = 4
+
+    # Target: prefer path 0->2->4 (the "middle path") over the perimeter
+    # but allow some flow on all paths for soft constraints
+    target_probs = torch.tensor(
+        [
+            [0.00, 0.10, 0.70, 0.10, 0.00],  # from 0
+            [0.00, 0.00, 0.10, 0.05, 0.05],  # from 1
+            [0.00, 0.00, 0.00, 0.10, 0.80],  # from 2 (the "middle")
+            [0.00, 0.00, 0.00, 0.00, 0.20],  # from 3
+            [0.00, 0.00, 0.00, 0.00, 0.00],  # from 4 (sink)
+        ]
+    )
+
+    machine = VariationalNetworkMachine(
+        n_nodes=n_nodes,
+        source_nodes=torch.tensor([source]),
+        sink_nodes=torch.tensor([sink]),
+        max_iter=30,
+        regularization="entropy",  # entropy reg → smoother gradient
+    )
+    optimizer = torch.optim.Adam(machine.parameters(), lr=0.2)
+
+    print(f"\nTarget match probabilities:")
+    print(target_probs)
+
+    print("\nTraining to match target routing pattern...")
+    initial_loss = None
+    for step in range(150):
+        optimizer.zero_grad()
+        result = machine()
+
+        # KL divergence between learned match probs and target
+        loss = F.kl_div(
+            (result["match_probs"] + 1e-8).log(),
+            target_probs,
+            reduction="batchmean",
+        )
+
+        if step == 0:
+            initial_loss = loss.item()
+        loss.backward()
+        # Gradient clipping
+        torch.nn.utils.clip_grad_norm_(machine.parameters(), 1.0)
+        optimizer.step()
+
+        if step % 25 == 0:
+            print(f"  Step {step:3d}: KL={loss.item():.4f}")
+
+    final = machine()["match_probs"].detach().numpy()
+    print(f"\nLearned match probabilities:")
+    print(final.round(3))
+    print(f"\nInitial KL: {initial_loss:.4f}")
+    print(f"Final KL:   {loss.item():.4f}")
+    print(f"Improvement: {((initial_loss - loss.item()) / initial_loss * 100):.1f}%")
+
+
+if __name__ == "__main__":
+    _demo_maze()
+    _demo_matching()
+    _demo_learning_loop()
+    print("\n✓ All demos completed.")

physarum_labs-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+physarum_labs/__init__.py,sha256=iBCuEtHSmj2Yz1ThbZLORAhMoYf76F6RENvr5spm5-E,1199
+physarum_labs/lp.py,sha256=xMMl8oAkSQ9xufwFI5yPNMjexe5JktkFIyNP-ddwYJw,14189
+physarum_labs/variational.py,sha256=ujqzI7seJX13qVOnyMlkz47b2GxNmq-ul-U_KCVmI-c,11758
+physarum_labs-0.2.0.dist-info/licenses/LICENSE,sha256=8Ht4G-SVSs28nnSktudsyUqYynfZGRH6VQ89ICX2Qik,1067
+physarum_labs-0.2.0.dist-info/METADATA,sha256=kKyGKIZpfVD2d1s1Osb6cg8DLZ41vWq7zMdo5i0jODQ,6315
+physarum_labs-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+physarum_labs-0.2.0.dist-info/top_level.txt,sha256=oYb0_iVP5BlfkrQkv0srzQZ_klLjYnbR0kjazoNGf_0,14
+physarum_labs-0.2.0.dist-info/RECORD,,

physarum_labs-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

physarum_labs-0.2.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+physarum_labs