syntropy-phi-c 0.4.0

A Fast Topological Heuristic for Connectome Pacemakers

Phi-C ($\Phi_C$): Topological Connectome Pacemaker

Phi-C is a high-performance Python library designed to rapidly identify Central Pattern Generators (CPGs) and rhythmic pacemakers in massive biological connectomes using algebraic topology.

Developed by the Syntropy Project (Alex Lopes da Silva).

---

🧠 The Problem

Finding autonomous oscillating regions in a brain (like the ones controlling breathing or locomotion) usually requires simulating the entire dynamic chemistry of the network, which becomes computationally intractable $O(2^N)$ in large mammalian brains.

Furthermore, naive structural density metrics often fall into the "Cerebellar Trap": flagging massive, dense, but purely feed-forward structures (like the cerebellum) as pacemakers.

⚡ The Solution

phi-c acts as a structural $O(E)$ pre-filter (linear in the number of edges for sparse connectomes). We combine two mathematical concepts:

1. Simplicial Nerve Scaling: A fast approximation of topological integration space using Min-Max normalized local clustering and eigenvector centrality.
2. Motif Discriminator: A strict graph-theoretic filter that penalizes unidirectional cliques and actively seeks reciprocal feedback loops ($A \rightleftharpoons B$).

By crossing these two metrics, the library instantly filters out false-positives and returns the absolute topological anatomical hotspots driving the network rhythm.

---

📦 Installation

pip install syntropy-phi-c

---

🚀 Quick Start

The library takes any standard directed graph (like a connectome exported from Electron Microscopy data) and returns the top pacemaker nodes.

import networkx as nx
from phi_c.pacemaker import find_pacemaker

# 1. Load a brain connectome (e.g., C. elegans)
connectome = nx.read_graphml("worm_brain.graphml")

# 2. Extract the top 5 Central Pattern Generators in milliseconds
cpg_hotspots = find_pacemaker(connectome, top_k=5)

# 3. View the results
for rank, (neuron, score) in enumerate(cpg_hotspots, 1):
    print(f"#{rank} - Neuron: {neuron} | Phi-C Score: {score:.2f}")

Advanced: Weighted Connectomes (fMRI, DTI)

If your graph edges carry synaptic strength or tract density, activate the weighted mode:

# Leverage synaptic weights for density calculation
cpg_hotspots = find_pacemaker(connectome, top_k=5, weight='weight')

---

📜 License

This project is dual-licensed:

1. Open Source: GNU AGPLv3 (Free for academic research and non-commercial public use).
2. Commercial License: For enterprise usage in proprietary medical software or SaaS APIs without AGPL obligations, please contact the author.

Copyright (C) 2026 Syntropy Project (Alex Lopes da Silva) and Contributors.