Neuronal Group Communication (NGC) reinterprets a large language model not as a monolithic stack of static weight matrices, but as a society of interacting neuronal groups. Each internal neural block is rewritten as a group of neurons represented by low-dimensional latent states. Communication topologies, or constitutions, specify which groups share latent state subspaces and therefore which internal communities are allowed to coordinate.

The central empirical and mechanistic claim is negotiated stability: successful reasoning emerges when internal communities can depart from the root model's routine trajectory while those departures remain bounded, verifiable, and globally stable. In the manuscript, compression is used as an experimental microscope: under a severe parameter budget, the model must reveal which communication structures are worth preserving.

This repository contains the sanitized core code and representative data needed to audit the main evidence threads:

• low-rank/shared-neuron materialization of NGC blocks;
• construction and scoring of communication constitutions;
• social-law analyses over proposer, skeptic, stabilizer, mediator, retrieval, and settlement roles;
• cached baseline comparisons and adaptive-router experiments;
• representative figures, tables, and source data supporting the manuscript.

NGC proceeds in five stages:

1. Rewrite neural blocks as neuronal groups. Dense weight matrices are represented through low-dimensional input/output neuronal states.
2. Open virtual communication channels. Groups may communicate through shared latent subspaces even when they are not adjacent in the original Transformer graph.
3. Construct a constitution bank. Candidate communication topologies are enumerated and materialized under a compression budget.
4. Score constitutions with social laws. Query-conditioned observables measure departure, stability, reconstruction fidelity, transport balance, spectral behavior, and cost.
5. Select and validate. Fixed or learned selectors choose a topology for inference; cached and executable audits quantify accuracy, cost, and mechanistic behavior.

For a neural block (b) with dense weight matrix

$$ W_b \in \mathbb{R}^{m_b \times n_b}, $$

NGC represents the block using low-dimensional neuronal state matrices

$$ Q_{b,\mathrm{in}} \in \mathbb{R}^{n_b \times r_b}, \qquad Q_{b,\mathrm{out}} \in \mathbb{R}^{m_b \times r_b}, \qquad r_b \ll \min(m_b,n_b). $$

The reconstructed communication strength is

$$ \widehat W_b[j,i] = \mu\left(Q_{b,\mathrm{out}}[j], Q_{b,\mathrm{in}}[i]\right), $$

where the minimal implementation uses the bilinear rule (\mu(u,v)=u^\top v). Under this view, a weight entry is no longer an isolated scalar parameter; it is a relation induced by the states of two neurons. Inter-group communication is implemented by aligning or sharing latent subspaces across blocks.

NGC is part of a continuing research program on replacing static, weight-centric neural computation with state-based, dynamics-aware, and geometry-aware neural representations. The current repository extends three prior works from our group: from dynamical neuron-state modeling, to Riemannian neural representation compression, and finally to neuronal-group communication inside LLMs.

Together, these works establish the intellectual trajectory behind this repository:

1. Dynamics-inspired neural representation: neural weights can be interpreted as relations induced by latent dynamical states.
2. Riemannian neuronal geometry: neural interaction can be modeled more efficiently through structured neuronal state spaces and learned metrics.
3. Neuronal Group Communication: LLM reasoning can be studied as the coordinated behavior of interacting neuronal groups under query-adaptive communication constitutions.

In this sense, the current NGC artifact is not only a compression toolkit. It is a research platform for investigating how efficient representation, dynamical stability, modular neural organization, and mechanistic interpretability can be unified under a communication-based view of large language models.

The following numbers are copied from the Jun 23 manuscript draft and are included here only as a high-level orientation. Accuracy is reported in percent. The full manuscript tables also report mean generated tokens in parentheses.

These snapshots are meant to orient readers. For reproducibility, use the scripts and source data described below rather than manually copying values from the README.

.
├── ngc_core/
│   └── nsys_utils/                 # Core shared-neuron / low-rank materialization utilities
├── v1/
│   ├── src/ngc_v1/                 # Shared social-law analysis utilities
│   └── scripts/                    # Constitutional observables, social laws, controls, publication artifacts
├── v2/
│   └── scripts/                    # Feature bank, cached baselines, adaptive router, phase/cost/causal controls
├── examples/
│   ├── sample_input/               # Reduced query-complete candidate bank for smoke tests
│   ├── source_data/                # Representative source data for manuscript-facing tables/figures
│   ├── figures/                    # Representative manuscript-facing figures
│   └── tables/                     # LaTeX table snippets copied from final experiment outputs
├── docs/
│   ├── artifact_map.md             # Mapping between scripts and manuscript evidence
│   ├── reproducibility_scope.md    # What this package can and cannot reproduce
│   ├── sanitization_report.md      # Release sanitization notes
│   └── validation_report.md        # Local checks and smoke-workflow validation
├── requirements.txt
└── README.md

The cached analysis workflow is intentionally lightweight and uses standard scientific Python packages.

git clone git@github.com:pzqpzq/NGC.git ngc
cd ngc

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

The minimal cached workflow uses numpy, pandas, scikit-learn, matplotlib, seaborn, joblib, tqdm, and pyarrow.

Live inference and NGC block materialization require user-managed model/runtime dependencies such as PyTorch, Transformers, CUDA-compatible drivers, and local model checkpoints. Those dependencies are not pinned in requirements.txt because the correct versions depend on the user's hardware and model family.

On some Linux conda environments, matplotlib may need the conda C++ runtime to appear before the system runtime:

export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:${LD_LIBRARY_PATH:-}"

The bundled candidate bank is a reduced, query-complete sample intended for fast repository validation. It contains:

• 16,748 candidate rows;
• 450 query groups;
• six model/dataset pairs: qwen3-8b and llama3-8b on gpqa, hotpot-qa, and math500;
• three topology families: NGC, Basis Sharing, and Vanilla SVD.

Run from the repository root:

mkdir -p outputs
cp -R examples/sample_input outputs/sample_run

python v2/scripts/02_run_baselines.py \
  --v2-root outputs/sample_run \
  --n-bootstrap 100

python v2/scripts/04_train_adaptive_router.py \
  --v2-root outputs/sample_run \
  --n-bootstrap 100

python v2/scripts/09_make_tables_and_figures.py \
  --v1-root v1 \
  --v2-root outputs/sample_run

For a very fast CI-style check, lower --n-bootstrap to 20. For more stable confidence intervals, increase it to 1000 or above.

Expected outputs include:

outputs/sample_run/results/baseline_compression_results.csv
outputs/sample_run/results/baseline_vs_ngc_bootstrap.csv
outputs/sample_run/results/router_holdout_results.csv
outputs/sample_run/results/table_insert_router_main.csv
outputs/sample_run/reports/final_experiment_digest_for_paper.md
outputs/sample_run/figures/baseline_accuracy_compression_curve.png
outputs/sample_run/figures/router_fixed_vs_adaptive_by_benchmark.png
outputs/sample_run/figures/router_oracle_gap.png
outputs/sample_run/figures/router_cost_accuracy_pareto.png

Set artifact roots explicitly for cached or live reruns:

export NGC_V0_ROOT=/path/to/NGC-v0-like-artifacts
export NGC_V1_ROOT=$PWD/v1
export NGC_V2_ROOT=/path/to/output-root

A cached v1-style sequence is:

python v1/scripts/01_build_constitutional_observables.py --v0-root "$NGC_V0_ROOT" --v1-root "$NGC_V1_ROOT"
python v1/scripts/02_social_law_atlas.py              --v0-root "$NGC_V0_ROOT" --v1-root "$NGC_V1_ROOT"
python v1/scripts/03_train_constitutional_selector.py --v0-root "$NGC_V0_ROOT" --v1-root "$NGC_V1_ROOT"
python v1/scripts/04_matched_law_breaking_controls.py --v0-root "$NGC_V0_ROOT" --v1-root "$NGC_V1_ROOT"
python v1/scripts/05_negotiated_stability_curve.py    --v0-root "$NGC_V0_ROOT" --v1-root "$NGC_V1_ROOT"
python v1/scripts/06_role_knockout_cached.py          --v0-root "$NGC_V0_ROOT" --v1-root "$NGC_V1_ROOT"
python v1/scripts/07_failure_taxonomy.py              --v0-root "$NGC_V0_ROOT" --v1-root "$NGC_V1_ROOT"
python v1/scripts/14_make_publication_artifacts.py    --v1-root "$NGC_V1_ROOT"

A cached v2-style sequence is:

python v2/scripts/01_build_feature_bank.py --v0-root "$NGC_V0_ROOT" --v1-root "$NGC_V1_ROOT" --v2-root "$NGC_V2_ROOT"
python v2/scripts/02_run_baselines.py      --v2-root "$NGC_V2_ROOT"
python v2/scripts/04_train_adaptive_router.py --v2-root "$NGC_V2_ROOT"
python v2/scripts/07_role_ablation.py      --v1-root "$NGC_V1_ROOT" --v2-root "$NGC_V2_ROOT"
python v2/scripts/09_make_tables_and_figures.py --v1-root "$NGC_V1_ROOT" --v2-root "$NGC_V2_ROOT"
python v2/scripts/10_phase_diagram_negotiated_stability.py --v2-root "$NGC_V2_ROOT"
python v2/scripts/13_make_jun15_artifacts.py --v2-root "$NGC_V2_ROOT"

The ngc_core/nsys_utils/ directory contains the implementation fragments that materialize NGC-style neural systems:

Example imports:

from ngc_core.nsys_utils.nsys_config import (
    SharedNeuronsHybrid2,
    SharedNeuronsHybrid3,
    LinearFromSharedNSys,
)
from ngc_core.nsys_utils.generate_ONT import generate_NeurTp

These laws are executable scoring functions over query-conditioned block observables. The anthropomorphic names are operational labels, not claims that LLMs contain literal human-like agents.

The cached scripts include exact comparisons for cached Vanilla SVD, Basis Sharing, and NGC candidates where corresponding candidates are present in the candidate bank. Some additional labels, such as ASVD-lite, Dobi-SVD-lite, SVD-LLM-V2-lite, and SoLA-lite, are proxy/cached diagnostics unless replaced by full upstream implementations. Keep these labels intact in derived reports unless you rerun the corresponding full methods.

Representative source data and manuscript-facing artifacts are provided under:

examples/source_data/v1_social_laws/
examples/source_data/v2_router_baselines/
examples/source_data/jun15_mechanistic_controls/
examples/figures/v1_social_laws/
examples/figures/v2_router_baselines/
examples/figures/jun15_mechanistic_controls/
examples/tables/

The sample candidate bank schema is documented in:

examples/sample_input/results/router_candidate_bank_schema.md

The package intentionally excludes:

• private server inventories, credentials, shell histories, and monitoring logs;
• model checkpoints, compressed checkpoints, and CUDA/model caches;
• full raw benchmark predictions and exhaustive candidate banks;
• private model/dataset loader files containing local filesystem paths;
• exploratory ablations not directly mapped to the manuscript's main claims.

Please cite the manuscript if you use this code or the released artifacts. Until the final bibliographic entry is available, use:

@misc{pei2026ngc,
  title        = {A Society of Neuronal Groups inside Large Language Models},
  author       = {Pei, Zhengqi and Huang, Qingming and Wang, Shuhui},
  year         = {2026},
  note         = {Manuscript draft and method-level reproducibility package}
}

Academic collaboration
In collaboration with the Institute of Computing Technology, Chinese Academy of Sciences.
Contact: peizhengqi22@mails.ucas.ac.cn

Business collaboration
In collaboration with Beijing Chipflow Technology Co., Ltd.. Contact: peizhengqi@chipflow.net