Metadata-Version: 2.2
Name: rnba
Version: 0.2.0
Summary: Recurrent Neural Blackboard Architecture - a simulation framework for neuro-cognitive modelling.
Author-Email: RNBA Contributors <m.dekamps@leeds.ac.uk>
License: MIT
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Project-URL: Homepage, https://github.com/RNBA/RNBA
Project-URL: Repository, https://github.com/RNBA/RNBA
Project-URL: Documentation, https://github.com/RNBA/RNBA#readme
Project-URL: Issues, https://github.com/RNBA/RNBA/issues
Requires-Python: >=3.8
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Provides-Extra: viz
Requires-Dist: graphviz>=0.20; extra == "viz"
Requires-Dist: matplotlib>=3.7; extra == "viz"
Provides-Extra: all
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: black>=22.0; extra == "all"
Requires-Dist: mypy>=0.990; extra == "all"
Requires-Dist: graphviz>=0.20; extra == "all"
Requires-Dist: matplotlib>=3.7; extra == "all"
Description-Content-Type: text/markdown

# RNBA — Replication of the Recurrent Neural Blackboard Architecture

In the paper [Sentences as connection paths: A neural language architecture of sentence structure in the brain (2022)](https://arxiv.org/abs/2206.01725), van der Velde presents a proposal for language representation in the brain. The model is a considerable extension of an earlier one [(van der Velde and de Kamps, 2006)](http://cambridge.org/core/journals/behavioral-and-brain-sciences/article/abs/neural-blackboard-architectures-of-combinatorial-structures-in-cognition/6A23B94D3E292F3B1F89D5745726E1CD). The simulations supporting the 2022 paper have been made public [(van der Velde, 2025)](https://doi.org/10.5281/zenodo.15472419). This project is a reimplementation of these simulations, with the aims of providing a pedagogical introduction to the paper and providing improved visualization of both the architecture and its dynamics.

The simulations are represented as is. The design decisions behind the original simulations are not questioned here, but where issues arise that may confuse the replication, they will be discussed.

## Purpose of this Repository

The simulations that were made available on Zenodo [(van der Velde, 2025)](https://doi.org/10.5281/zenodo.15472419) serve the important purpose of making the simulations of van der Velde (2022) reproducible, but they are not very transparent in exposing the computational elements of the RNBA. The simulator presented here serves a dual purpose:

- To serve as departure point for extensions of the RNBA architecture that are investigated at the University of Leeds
- To make the computational structure of the RNBA architecture more transparent than shown in the Zenodo repository, so that new researchers can get up to speed more quickly. To this end, there are a number of Jupyter notebooks in the `examples/` folder.

## Installation

For most users:

```bash
pip install rnba
```

This installs the Python package **and** a precompiled C++ simulator (`rnba-sim`) — no compiler needed. Wheels are published for Linux (x86_64, aarch64), macOS (Intel, Apple Silicon) and Windows.

For development, clone the repository and install editable. Because `pip install` also builds the C++ simulator from source, this requires **CMake ≥ 3.15 and a C++17 compiler** in addition to Python ≥ 3.8:

```bash
git clone https://github.com/dekamps/RNBACode.git
cd RNBACode
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

Plotting and visualization extras: `pip install "rnba[viz]"` (matplotlib + graphviz bindings).

## Running Simulations

This is the typical use of the package. A simulation needs:

1. an **architecture file** describing the complete neural blackboard (e.g. `tests/RNBA_arch_SGall_SNB15.txt`);
2. an **instruction file** giving the timings at which populations are switched on and off — word inputs, gating populations, etc. Both instruction formats (QA and SGall) are accepted and auto-detected; they are fully documented in [docs/instruction-file-formats.md](docs/instruction-file-formats.md);
3. optionally a **bindings file**, which pre-stores bindings in the network, emulating sentences that were read into the blackboard previously (e.g. `tests/RNBA_SGall_SNB15_Bindings_Sentence_3NVN.txt`).

The output is a CSV with one row per timestep (`h = 0.1` ms) and one column per population.

### Python simulator: `rnba-run`

```bash
rnba-run \
  --architecture tests/RNBA_arch_SGall_SNB15.txt \
  --instruction  tests/QA_3NVN_O_success.txt \
  --bindings     tests/RNBA_SGall_SNB15_Bindings_Sentence_3NVN.txt \
  --output       qa_trace.csv \
  --output-row-map qa_row_map.csv \
  --output-named
```

Useful options:

- Duration is derived automatically from the instruction schedule (plus `--tail-steps`, default 500). Override with `--t-end MS` or `--n-steps N`; values that would truncate the schedule are rejected.
- `--output-row-map FILE` writes the row-index ↔ `pop_id` mapping needed by the plotting tools.
- `--output-named` additionally writes the trace with human-readable `pop_id[row]` column headers (`<output>_named.csv`).
- `--output-inputs FILE` writes the external input traces.
- `--engine state_update` (default, mirrors the C++ solver) or `--engine odeint_chunks`.

(In a source checkout without installation, use `python -m rnba.simulation` with the same arguments.)

### C++ simulator: `rnba-sim`

The C++ simulator is functionally equivalent and considerably faster. It reads a JSON *simulation contract* instead of the architecture text file; generate one first:

```bash
python cpp-sim/tools/export_network.py \
  --load-from tests/RNBA_arch_SGall_SNB15.txt \
  --output snb15_contract.json
```

(Ready-made contracts for common configurations are committed under `cpp-sim/data/`.)

Then run, with the same instruction/bindings files as the Python simulator:

```bash
rnba-sim \
  --model         snb15_contract.json \
  --instructions  tests/QA_3NVN_O_success.txt \
  --bindings      tests/RNBA_SGall_SNB15_Bindings_Sentence_3NVN.txt \
  --t-end         180.0 \
  --output        qa_trace_cpp.csv \
  --output-row-map qa_row_map.csv
```

`rnba-sim --help` documents all options. Both simulators produce the same CSV format, so the inspection tools below work with either.

## Inspecting Results

### Activation plots for named populations: `rnba-plot`

Populations are usually selected by their descriptive `pop_id` (see naming conventions below). Given a trace CSV and the row map:

```bash
# All rows whose pop_id is MA_Word_A1
rnba-plot --csv qa_trace.csv --row-map qa_row_map.csv \
          --pop MA_Word_A1 --out word_A1.png

# A specific population instance, and a raw row index
rnba-plot --csv qa_trace.csv --row-map qa_row_map.csv \
          --pop 'GC_start_G1[158]' --pop 42 --out mixed.png
```

`--pop` may be repeated; `--architecture arch.txt` can replace `--row-map`; on a `*_named.csv` written by `rnba-run --output-named`, no mapping file is needed at all. `--t-min/--t-max` restrict the time window. Requires `pip install "rnba[viz]"`.

### Activity-flow video

The schematic activity-flow renderer overlays simulation traces on the SNB15 schematic and can render a video (requires `ffmpeg`):

```bash
python -m rnba.visualize_activity_flow \
  --architecture tests/RNBA_arch_SGall_SNB15.txt \
  --trace-csv    qa_trace.csv \
  --inputs-csv   qa_inputs.csv \
  --out-dir      activity_flow_out \
  --render-video \
  --frames-dir   activity_flow_out/frames \
  --video-out    qa_activity.mp4 \
  --fps 25 --step-ms 1.0
```

See `python -m rnba.visualize_activity_flow --help` for the full option set (codec, styling, frame selection).

## Quick Start: Replicating the QA Simulation

The file `examples/example_qa_simulation.py` is a faithful replication of the Zenodo simulation performed in the original `RNBA24_sim_QA_3NVN.py` (kept in `legacy/`). It takes roughly 15 minutes to run. The workflow:

1. Read the complete blackboard architecture from `tests/RNBA_arch_SGall_SNB15.txt`.
2. Apply the bindings file `tests/RNBA_SGall_SNB15_Bindings_Sentence_3NVN.txt`, which pre-stores bindings in the network, emulating sentences previously read into the network.
3. Read the instruction files `tests/QA_3NVN_O_success.txt` and `tests/QA_3NVN_O_fail.txt` (QA format).
4. Run both simulations.
5. Inspect the results in `examples/example_qa_output/`: `qa_3nvn_word_populations_success.png` and `qa_3nvn_word_populations_fail.png` replicate Fig. 4 in van der Velde (2026).

## Examples

See the `examples/` folder for Jupyter notebooks demonstrating RNBA usage:

- **Example_01_WIlsonCowan.ipynb**: Two-population excitatory/inhibitory (E/I) circuit demonstrating Wilson-Cowan dynamics with external input.
- **Example_02_BasicCircuits.ipynb**: Complete RNBA circuit architecture including Wilson-Cowan populations, Working Memory, Gating circuits, and Binding circuits. Demonstrates the four fundamental circuit types from the original simulations.

For further examples, see the README.md in the examples folder.

```bash
pip install -e ".[dev]"
jupyter notebook examples/
```

Each notebook is self-contained and can be executed end-to-end.

### Programmatic Architecture Build

The repository includes a script that programmatically rebuilds the architecture from the analysis text file:

```bash
python examples/example_network_creation.py
```

This script:
- Loads `examples/RNBA_arch_SGall_SNB15.txt`
- Builds a `Network` using the current core primitives/wrappers as family coverage references
- Creates network nodes with **canonical runtime IDs** (row indices as strings)
- Tracks architecture row IDs (`idx`) to descriptive `pop_id` labels
- Reconstructs connectivity from the text specification and reports summary counts

### Node Naming Conventions (row_id vs pop_id)

RNBA uses **two complementary naming schemes**:

- **Canonical runtime ID (row_id):** for **normal populations**, the node name is the row index as a string (e.g., `"158"`). This is the stable, unique ID used by `load_architecture` and runtime networks.
- **Descriptive label (pop_id):** a human-readable role name such as `GC_start_G1`, `SA_WM_SG1Verb_B9`, etc. These repeat across rows, so **pop_id alone is not unique** for normal populations.
- **Unique descriptive label:** `pop_id[row_id]` (e.g., `GC_start_G1[158]`) is unique and readable; this is what `rnba-run --output-named` and the converter emit when relabeling traces.
- **External inputs:** their runtime name **is** `pop_id` (these are unique).

**Conversion helpers:**

- `rnba.converters.architecture.parse_architecture_txt` + `build_row_index_map` → `row_map[idx].pop_id`
- `rnba.converters.architecture.relabel_trace_headers` → `pop_id[row_id]` labels (CLI: `rnba-arch-convert --relabel-trace`)
- After `load_architecture`, `net.population_metadata[str(idx)]["pop_id"]` yields the label for a node.

## Documentation

Project documentation lives in the docs/ folder:
- Instruction file formats (QA and SGall): docs/instruction-file-formats.md
- Analysis: docs/analysis/
- Design notes: docs/design/
- Circuit library design and implementation status: docs/design/CIRCUIT_LIBRARY_DESIGN.md

### Circuit Factory Functions

The circuit library provides factory functions that create topologically identical circuits with different template names. This naming convention supports explicit traceability to roles in `RNBA_arch_SGall_SNB15.txt`.

**Core topologies:**
- `create_gating_circuit` / `create_inhibgate_circuit` / `create_gate_sg_cm_circuit` / `create_gate_sg_w_circuit` / `create_gate_lma_w_pos_circuit` / `create_linked_bgate_dtoh_circuit` — all gating topology (differ only in template name)
- `create_wm_circuit` — working memory topology
- `create_bgate_circuit` — binding gate topology
- `create_linked_bgate_circuit` — linked binding gate topology
- `create_sg_core_circuit` — SG competition/bridge core topology

**Naming convention:** When building the full architecture programmatically (as in `example_network_creation.py`), circuit names are deliberately chosen to match their architectural roles. For example:
- A gate intended for SG→CM binding uses `create_gate_sg_cm_circuit()` to register with template name `"Gate_SG_CM_circuit"`
- A gate intended for SG→W binding uses `create_gate_sg_w_circuit()` to register with template name `"Gate_SG_W_circuit"`

This makes instantiated circuit names traceable to specific roles in the architecture specification.

Example:

```python
from rnba.circuits import create_gating_circuit, create_gate_sg_cm_circuit
from rnba.network import Network

net = Network()

# For a generic gate role
net.register_circuit(create_gating_circuit(w_internal=0.2))

# For explicit SG→CM role (same topology, different template name for traceability)
net.register_circuit(create_gate_sg_cm_circuit(w_internal=0.2))

# Both create instances with names matching their architectural intent
instance1 = net.instantiate_circuit("Gating_circuit", "gate_0")
instance2 = net.instantiate_circuit("Gate_SG_CM_circuit", "sg_cm_gate_0")
```

### Network Visualization

The RNBA package includes a **graphviz-based visualization module** (`rnba.visualize`) that renders networks as diagrams. This is useful for understanding network architecture and debugging connectivity.

**Features:**
- **Detailed view**: Visualizes all nodes (populations) and connections in your network
- **Abstract view**: Shows circuits as single boxes (aggregate view of circuit-level architecture)
- Color-codes nodes by type (red=excitatory, blue=inhibitory, gray=other)
- Shows connection weights and direction
- Groups nodes by circuit instance with light gray boxes
- Supports multiple layout directions (top-to-bottom, left-to-right)
- Exports to PNG, SVG, PDF, and other formats

**Quick start:**
```bash
# Install visualization dependencies
pip install -e ".[viz]"

# Requires graphviz system package:
# macOS: brew install graphviz
# Ubuntu/Debian: sudo apt-get install graphviz
# Windows: https://graphviz.org/download/

# Run the demo to see both visualization modes
python examples/demo_network_visualization.py
```

This generates PNG diagrams of the example_2 network in your current directory (both detailed and abstract views).

**Usage in your code:**
```python
from rnba.visualize import visualize_network

# Detailed view (all nodes and populations)
visualize_network(
    network=my_network,
    output_file="my_network_detailed",
    format="png",
    show_weights=True,
    group_by_circuit=True,
    rankdir="TB"  # "TB" for top-to-bottom, "LR" for left-to-right
)

# Abstract view (circuits as boxes)
visualize_network(
    network=my_network,
    output_file="my_network_abstract",
    format="png",
    show_weights=True,
    abstract_circuits=True,  # <-- Enable abstract circuit-level view
    rankdir="TB"
)
```

**When to use each view:**
- **Detailed**: Debugging internal circuit connectivity, understanding population dynamics
- **Abstract**: Getting high-level overview of circuit architecture, understanding inter-circuit communication patterns

See `tests/test_visualize.py` for additional examples.

### Full-Scale Architecture Visualisation

The graphviz module above is suited to small hand-built networks and circuit diagrams. For the full RNBA architecture (16,000–32,000 populations), a separate pipeline exists that uses **GEXF + ForceAtlas 2 (Gephi) + matplotlib**.

The complete pipeline — including all automated steps, the manual Gephi layout step, FA2 settings, output file descriptions, and instructions for what to do when the architecture changes — is documented and driven by:

```bash
bash examples/visualize_architecture.sh
```

That script is the authoritative runbook for full-scale network visualisation. It produces:
- Grey GEXF files for import into Gephi (automated)
- Coloured circle GEXF files with external populations on a ring (automated, requires committed FA2 exports)
- Rendered PNGs at 300 dpi for both the 16k and 32k E/I layouts

### SNB15 Schematic Visualisation (Collapsed Motif View)

The repository also includes a standalone schematic renderer:
- rnba/schematic_visualization.py

This script produces the compact SNB15 motif-style figures used during gate-marker
and linked-binding visual checks.

From the repository root, use these exact commands:

Generate the 4-row view:

python -m rnba.schematic_visualization --first-rows 4 --formats png --basename word_assemblies_schematic_first4

Generate the full 15-row view:

python -m rnba.schematic_visualization --formats png --basename word_assemblies_schematic_full15

### Reference Plots (Canonical Commands)

For future reproducibility, these are the two exact reference renders.

1) Colour plot with SG competition in full mode:

```bash
source .venv/bin/activate && python -m rnba.schematic_visualization --show-control-nodes --show-output-path --show-sg-competition --sg-competition-mode full --formats pdf --basename word_assemblies_schematic_controls_flow_option3a_interleaved_v21_sgcomp_full
```

Expected output file:

- `word_assemblies_schematic_controls_flow_option3a_interleaved_v21_sgcomp_full.pdf`

2) Dark-mode plot without SG competition:

```bash
source .venv/bin/activate && python -m rnba.schematic_visualization --show-control-nodes --show-output-path --activity-flow-theme --formats pdf --basename word_assemblies_schematic_controls_flow_dark_option3a_interleaved_v22_no_sgcomp
```

Expected output file:

- `word_assemblies_schematic_controls_flow_dark_option3a_interleaved_v22_no_sgcomp.pdf`

## Development

**Run tests:**
```bash
# All tests (unit + integration)
pytest tests/ -v

# Unit tests only (skip slower integration tests)
pytest tests/ -m "not integration" -v

# Integration tests only
pytest tests/integration/ -v
```

**C++ simulator development build** (separate from the pip build):
```bash
cmake -B cpp-sim/build cpp-sim
cmake --build cpp-sim/build -j
ctest --test-dir cpp-sim/build
```

**Experiments folder**: The `experiments/` directory (not version-controlled) is a scratch space for developing new use cases and prototypes before promoting polished examples to the `examples/` folder. Legacy pre-package scripts are preserved in `legacy/`.

License: MIT
