rnba 0.2.2__tar.gz → 0.2.3__tar.gz

{rnba-0.2.2 → rnba-0.2.3}/.gitignore

@@ -62,6 +62,13 @@ bla.py
 /*.pdf
 examples/*.pdf
 
+# LaTeX build artifacts from docs/ sources (docs/templates PDFs stay tracked;
+# these globs match the docs/ root only, not subdirectories)
+docs/*.aux
+docs/*.log
+docs/*.out
+docs/simulation-and-visualization-workflow.pdf
+
 # Local experiment outputs in tracked_experiments (only the scripts and
 # sentence inputs there are tracked)
 tracked_experiments/activity_flow_*/

{rnba-0.2.2 → rnba-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: rnba
-Version: 0.2.2
+Version: 0.2.3
 Summary: Recurrent Neural Blackboard Architecture - a simulation framework for neuro-cognitive modelling.
 Author-Email: RNBA Contributors <m.dekamps@leeds.ac.uk>
 License: MIT
@@ -226,6 +226,7 @@ RNBA uses **two complementary naming schemes**:
 ## Documentation
 
 Project documentation lives in the docs/ folder:
+- Simulation-to-video workflow (LaTeX): [docs/simulation-and-visualization-workflow.tex](docs/simulation-and-visualization-workflow.tex)
 - Instruction file format (unified; legacy QA and SGall dialects): [docs/instruction-file-formats.md](docs/instruction-file-formats.md)
 - Bindings file format: [docs/bindings-file-format.md](docs/bindings-file-format.md)
 - Analysis: [docs/analysis/](docs/analysis/)

{rnba-0.2.2 → rnba-0.2.3}/README.md

@@ -189,6 +189,7 @@ RNBA uses **two complementary naming schemes**:
 ## Documentation
 
 Project documentation lives in the docs/ folder:
+- Simulation-to-video workflow (LaTeX): [docs/simulation-and-visualization-workflow.tex](docs/simulation-and-visualization-workflow.tex)
 - Instruction file format (unified; legacy QA and SGall dialects): [docs/instruction-file-formats.md](docs/instruction-file-formats.md)
 - Bindings file format: [docs/bindings-file-format.md](docs/bindings-file-format.md)
 - Analysis: [docs/analysis/](docs/analysis/)

rnba-0.2.3/docs/activity-flow-colour-coding.md

@@ -0,0 +1,344 @@
+# Activity-flow video: colour coding
+
+How `rnba.visualize_activity_flow` colours the compressed schematic, what
+that colouring expresses in terms of the published RNBA model, and where
+the implementation currently diverges.
+
+The reference is van der Velde, *The recursive neural blackboard
+architecture for combinatorial sentence structures in the brain*
+(`FvdV-RNBA26-article.pdf`) and its Supplementary Material
+(`FvdV-RNBA26-SM.pdf`, cited below as **SM**).
+
+## 1. The compressed representation
+
+The video does not draw one marker per population. It draws a *template*
+schematic in which each marker stands for a circuit — several populations
+collapsed into one symbol. Each symbol therefore needs a population
+chosen to speak for it:
+
+- the **activity representative** — the population whose trace stands for
+  the circuit's activity. For gating circuits this is the gate output,
+  `GC_gate_G4`.
+- the **WM representative** — the circuit's working-memory pair,
+  `WM1_Apop` / `WM2_Bpop`. Some circuits have one; most do not.
+
+SM A.2: a WM population is *simulated* as two interacting populations A
+and B, of which "population A is seen and referred to as the WM
+population, because it alone receives input activity from the rest of the
+architecture and generates excitatory output"; the activities of A and B
+"are summarized as WM activity in the simulations."
+
+## 2. Semantics, derived from SM I.1
+
+SM I.1 partitions every SNB population into three categories:
+
+- **Gating** — all populations in gating and linked-binding circuits,
+  *except* the WM populations in the latter.
+- **WM** — all A and B populations forming WM populations.
+- **Other** — all remaining SNB populations, "such as the word
+  populations".
+
+This is the model's own distinction between **control** and **stored
+structure**, and it is load-bearing in the paper: Figures 4B/4C plot
+Gating, WM and Other as separate curves, and the central result is that
+Total activity "is dominated by Gating, related to the control of
+sentence processing," while the contribution of WM — "related to storing
+a sentence/constituent structure" — is "small and 'flat'."
+
+**The colour scheme is the spatial analogue of that plot:**
+
+| Colour | Meaning | SM I.1 category |
+| --- | --- | --- |
+| **Red** | control activity — a gate is passing signal | Gating |
+| **Yellow** | stored structure — a WM is latched | WM |
+| **Orange** | both at once | Gating + WM |
+| Grey | below threshold; inactive baseline | — |
+
+Yellow is the signature of persistence. Per SM D.1.1, an LMA *is* a WM
+population and "remains active until a new LMA of the same type is
+activated" — so a latched LMA should read yellow for as long as it holds
+its content.
+
+### Category assignment is mechanical
+
+A population's category follows from its `pop_id` alone:
+
+| `pop_id` | Category |
+| --- | --- |
+| `WM1_Apop`, `WM2_Bpop` | WM |
+| `GC_start_G1`, `GC_disinhibition_G2`, `GC_inhibition_G3`, `GC_gate_G4` | Gating |
+| anything else | Other |
+
+Applying that rule to `RNBA_arch_SGall_SNB15.txt` reproduces SM table S15
+exactly:
+
+| Category | This repo | SM table S15 (SNB15) |
+| --- | ---: | ---: |
+| Gating | 10980 | 10980 ✓ |
+| WM | 2970 | 2970 ✓ |
+| Other | 2190 | 2190 ✓ |
+| Total | 16140 | 16140 ✓ |
+| External | 158 | 158 ✓ |
+| Total in simulation | 16298 | 16298 ✓ |
+
+(16298 is also the `lenlist` in the architecture file header.) The 2970 WM
+populations are **1485 WM pairs**.
+
+### Blue
+
+`WORD_INHIB` symbols and the single global competition node take a
+separate branch and render blue. This has no counterpart in SM I.1 —
+their representatives (`MA_Word_inhib_A1a`) are **Other** populations. See
+§6, finding D.
+
+## 3. As implemented
+
+Each symbol gets two independent intensities per frame.
+
+**Activity representative** — `_value_for_mapping`
+(`rnba/visualize_activity_flow.py:1152`): the `primary_index` row, or
+`max(primary, secondary)` when the mapping mode is not `direct`.
+
+**WM representative** — `_value_for_wm` (`:1160`): `max(wm1, wm2)`, or
+`0.0` when either index is `-1`. (SM A.2 says the two are "summarized";
+the code takes the max.)
+
+Both pass through `_normalize_activity` (`:1166`): values below
+`--activation-threshold` (default `1.0`) clamp to zero, the remainder
+rescales against `--vmax` (default `100.0`) and is raised to
+`--activation-gamma` (default `0.7`).
+
+The two are decomposed (`:1418-1421`) and mixed (`:1432-1435`):
+
+```python
+overlap  = min(t_rep, t_wm)
+rep_only = t_rep - overlap
+wm_only  = t_wm  - overlap
+
+r = 1.00 * rep_only + 1.00 * overlap + 0.95 * wm_only
+g = 0.04 * rep_only + 0.58 * overlap + 0.95 * wm_only
+b = 0.06                                    # constant
+alpha = 0.40 + 0.60 * max(t_rep, t_wm)
+```
+
+The explicit decomposition exists so overlap reads orange rather than
+collapsing to yellow. Blue is a separate branch (`:1424-1429`) using the
+activity representative only. Marker size scales with
+`max(t_rep, t_wm)` (`:1440`); `WORD` symbols draw at double size.
+
+**Readability.** `b` is pinned at `0.06`, so red, orange and yellow differ
+*only in the green channel*. At low `--dpi` and small markers they are
+easy to confuse, and a latched-but-dim symbol is both faint (alpha floor
+`0.40`) and colour-ambiguous. `--first-rows N` helps: it scales overlay
+markers 3x (`:1296`).
+
+> The constants above were hand-tuned, not derived. The commit that
+> established the current rendering path (`82691ab`) says "Colors and
+> transparency still need further tuning." Sections 1–2 are the
+> specification; §3 is what the code currently does.
+
+## 4. Conformance table
+
+Audited against a full SNB15 run (2064 symbols, all mapped).
+
+| Family | N | Representative | SM category | WM bound | Reachable colours |
+| --- | ---: | --- | --- | :-: | --- |
+| `CM_CELL` | 225 | `Bgate_HtoD_C1::GC_gate_G4` | Gating | yes | red, yellow, orange |
+| `SG_H` | 165 | `SA_SG<t>_B4::WM1_Apop` | **WM** | yes | orange → yellow |
+| `SG_D` | 165 | `SA_SG<t>_B4::WM1_Apop` | **WM** | yes | orange → yellow |
+| `LMA_OUT_H` | 135 | `Gate_LMA_W_<wt>_B2a::GC_gate_G4` | Gating | yes | red, yellow, orange |
+| `LMA_OUT_D` | 135 | `Gate_LMA_W_<wt>_B2a::GC_gate_G4` | Gating | yes | red, yellow, orange |
+| `SGIN_H` | 165 | `Gate_SG_CM_SG<t>_B8::GC_gate_G4` | Gating | no | red only |
+| `SGIN_D` | 165 | `Gate_SG_CM_SG<t>_B8::GC_gate_G4` | Gating | no | red only |
+| `SG_OUT_H` | 165 | `Gate_SG_W_SG<t>_B12::GC_gate_G4` | Gating | no | red only |
+| `SG_OUT_D` | 165 | `Gate_SG_W_SG<t>_B12::GC_gate_G4` | Gating | no | red only |
+| `B2_LINK_H` | 165 | `L_Bgate_SG<t>_W_B2::GC_gate_G4` | Gating | yes | red, yellow, orange |
+| `B2_LINK_D` | 165 | `L_Bgate_SG<t>_W_B2::GC_gate_G4` | Gating | yes | red, yellow, orange |
+| `WORD` | 15 | `MA_Word_A1` | **Other** | no | red only |
+| `H_RELAY` | 15 | `HD_Row_CM_in_B10` | **Other** | no | red only |
+| `D_RELAY` | 15 | `HD_Row_CM_in_B10` | **Other** | no | red only |
+| `CM_OUT_H` | 15 | `HD_Row_CM_out_B11` | **Other** | no | red only |
+| `CM_OUT_D` | 15 | `HD_Row_CM_out_B11` | **Other** | no | red only |
+| `WORD_INHIB` | 15 | `MA_Word_inhib_A1a` | **Other** | no | blue |
+| `GLOBAL_INHIB` | 1 | none — synthesised `max` over `WORDINHIB_*` (`:1354-1361`) | — | no | blue |
+| `INPUT` | 158 | external input rows | External | no | red only |
+
+Symbols by SM category of their representative: **Gating 1485, WM 330,
+Other 90, External 158, synthesised 1**.
+
+### WM coverage
+
+A WM must be attributed to the circuit that *owns* it, not to the
+`circ_id` it happens to be filed under. Per SM A.4 a linked-binding
+circuit is **two gating circuits sharing one WM population**; the row map
+files that shared WM under the forward gate, so reading ownership off
+`circ_id` double-counts and mislabels.
+
+Verified in the architecture — `Bgate_SG1Verb_B1::WM1_Apop` (row 349)
+outputs to `Bgate_SG1Verb_B1::GC_disinhibition_G2` (352) **and**
+`L_Bgate_SG1Verb_W_B2::GC_disinhibition_G2` (416). Same pattern for
+`Bgate_W_C_A2::WM1_Apop` (172) → (175) and (223).
+
+Of the architecture's **1485 WM pairs**, symbols are bound to
+**1020 (69%)**:
+
+| WM owner | Pairs | Gates sharing it | Symbol |
+| --- | ---: | --- | --- |
+| CM binding cell | 225 | `Bgate_HtoD_C1` + `L_Bgate_DtoH_C2` | `CM_CELL` ✓ |
+| LMA→SG linked-binding | 330 | `Bgate_SG<t>_B1` + `L_Bgate_SG<t>_W_B2` | `B2_LINK_H/D` ✓ (§6 B) |
+| SG sub-assembly (SA) | 330 | standalone WM in the SG circuit | `SG_H`/`SG_D` ✓ |
+| LMA (`MA_<wt>_A3`) | 135 | standalone WM population | `LMA_OUT_H/D` ✓ (§6 A) |
+| SA-WM (`SA_WM_SG<t>_B9`) | 330 | standalone WM in the SG circuit | **none** (§6 C) |
+| LMA↔W linked-binding | 135 | `Bgate_W_<wt>_A2` + `L_Bgate_LMA_W_<wt>_A2a` | **none** (§6 C) |
+
+The video therefore shows 69% of the model's stored sentence structure —
+the quantity the paper isolates as the WM category.
+
+## 5. Design notes (not defects)
+
+**SG symbols represent a WM population, by design.** SM D.1.5: "The core
+population of an SG circuit is a WM population referred to as a
+sub-assembly (SA)." So for all 330 `SG_H`/`SG_D` symbols
+`primary_index == wm1_index` — the SA *is* both the representative and
+the WM. Consequently `rep_only` is structurally zero and these symbols
+never render pure red; they sit orange and drift yellow as `WM2_Bpop`
+outruns `WM1_Apop`. That reflects the architecture rather than
+contradicting it. It does mean the red/yellow contrast carries no
+information on SG nodes: they are WM nodes throughout.
+
+**`Gate_LMA_W_<wt>_B2a` is not the LMA.** Despite the `LMA_OUT_*` family
+name it is the LMA-selective gating circuit on the CM→W *output* path
+(`D-N-out` / `H-V-out` in SM figure S9), disinhibited by
+`EX8H/D_LMA_out_<wt>_<arm>`. In a run with no retrieval phase it
+correctly stays silent for the whole simulation.
+
+## 6. Defects
+
+### A — LMA symbols had no WM binding — **FIXED**
+
+`_build_mappings` did attempt a WM pair for `LMA_OUT_H`/`LMA_OUT_D`, but
+searched the wrong circuit:
+
+```python
+circ = f"Gate_LMA_W_{s.sg_type}_B2a"
+wm1, wm2 = _find_wm_pair(rows, circ_id=circ, ..., mat_id="S_G")   # was
+```
+
+`Gate_LMA_W_<wt>_B2a` contains only the four `GC_*` gate populations — no
+WM at all. The LMA lives in a different circuit, `MA_<wt>_A3`, which holds
+exactly `WM1_Apop`/`WM2_Bpop`. The lookup silently returned `(-1, -1)`,
+so `t_wm = 0` and yellow was arithmetically unreachable for all 270 LMA
+symbols — defeating the defining property in SM D.1.1.
+
+The lookup is now keyed on the LMA circuit and the word group:
+
+```python
+wm1, wm2 = _find_wm_pair(rows, circ_id=f"MA_{s.sg_type}_A3",
+                         mat_id=f"W_G{s.row}")                    # now
+```
+
+All 270 LMA symbols now resolve a WM pair, verified correct for every
+word type and row. Because `Gate_LMA_W_<wt>_B2a` exists per arm (270)
+while `MA_<wt>_A3` is per row (135), the H and D symbols of a row share
+one latch and light together.
+
+Worked example — "Sue eats pizza", the C LMA of row 1:
+
+| Row | Circuit :: population | Peak | Before | After |
+| --- | --- | ---: | --- | --- |
+| 254 | `MA_C_A3::WM1_Apop` | 99.99 | unmapped | **bound as `wm1`** |
+| 255 | `MA_C_A3::WM2_Bpop` | 100.00 | unmapped | **bound as `wm2`** |
+| 714 | `Gate_LMA_W_C_B2a::GC_gate_G4` (H) | 0.005 | representative | representative |
+| 1059 | `Gate_LMA_W_C_B2a::GC_gate_G4` (D) | 0.005 | representative | representative |
+| 158 | `MA_Word_A1[W_G0]` | 98.17 @ 10 ms | red flash, gone by ~25 ms | unchanged |
+
+The C LMA holds `WM2 = 100` from ~15 ms until inhibited at 140 ms by
+`MA_C_inhib_A3a` (the `Clause_inhib` instruction). Colour of
+`LMAOUT_H_r00_C` after the fix, computed with the renderer's own maths:
+
+| t (ms) | rep | WM | `t_rep` | `t_wm` | Colour |
+| ---: | ---: | ---: | ---: | ---: | --- |
+| 0 | 0.00 | 0.00 | 0.000 | 0.000 | grey |
+| 20 | 0.00 | 99.89 | 0.000 | 0.999 | **yellow** |
+| 60 | 0.00 | 100.00 | 0.000 | 1.000 | **yellow** |
+| 100 | 0.00 | 100.00 | 0.000 | 1.000 | **yellow** |
+| 140 | 0.00 | 100.00 | 0.000 | 1.000 | **yellow** |
+| 160 | 0.00 | 0.20 | 0.000 | 0.000 | grey |
+| 200 | 0.00 | 0.00 | 0.000 | 0.000 | grey |
+
+Yellow across exactly the latched stretch, extinguishing with the
+commanded inhibition — the SM D.1.1 signature.
+
+### B — `B2_LINK` symbols had no WM binding — **FIXED**
+
+The same class of error as A. `B2_LINK_H`/`B2_LINK_D` draw the reverse
+gate of the LMA→SG linked-binding circuit, and the WM lookup searched
+that gate's own `circ_id`:
+
+```python
+circ = f"L_Bgate_{s.sg_type}_W_B2"
+wm1, wm2 = _find_wm_pair(rows, circ_id=circ, ..., mat_id="S_G")   # was
+```
+
+The shared WM is filed under the *forward* gate. The row/`mat_id` keys
+were already correct; only the circuit was wrong:
+
+```python
+wm1, wm2 = _find_wm_pair(rows, circ_id=f"Bgate_{s.sg_type}_B1",
+                         h_row=..., d_row=..., mat_id="S_G")      # now
+```
+
+All 330 `B2_LINK` symbols now resolve a WM pair, verified correct for
+every SG type and row. Combined with A, WM coverage rises 555 → 1020 of
+1485 pairs (37% → 69%).
+
+### C — Two WM owners have no symbol at all
+
+- **LMA↔W linked-binding** (135 pairs). *Neither* of its gates —
+  `Bgate_W_<wt>_A2` or `L_Bgate_LMA_W_<wt>_A2a` — is on the schematic,
+  even though Figure 1B draws this binding prominently as the black
+  diamond between the word population and the LMA. In the §6 A worked
+  example it latched at `WM1≈50`, `WM2≈100` and held past the end of the
+  run, entirely unseen.
+- **SA-WM** (`SA_WM_SG<t>_B9`, 330 pairs). A standalone WM inside the SG
+  circuit (SM D.1.5, figure S8), with no symbol of its own.
+
+Unlike A and B these cannot be fixed in the mapper: there is no symbol to
+attach a WM to. Closing them requires **new symbols in the schematic
+template** (`rnba/schematic_visualization.py`, and correspondingly the
+reference PDFs under `docs/templates/`), which changes the canonical
+static schematic as well as the video. That is a modelling/design
+decision, not a bug fix.
+
+### D — The Other category is split arbitrarily between red and blue
+
+SM I.1 makes Other a first-class category, plotted separately in figure
+4B. In the renderer its 90 symbols are split: 15 (`WORD_INHIB`) render
+blue, the other 75 (`WORD`, `H_RELAY`, `D_RELAY`, `CM_OUT_H`, `CM_OUT_D`)
+render red and are indistinguishable from Gating symbols. Neither the
+blue branch nor the red default corresponds to a category boundary in the
+model.
+
+### E — Cosmetic
+
+`raw_rep` at `:1409` is computed and discarded; `t_rep` comes from the
+precomputed `src_activity` map at `:1412`. Same value, redundant work.
+
+## 7. Reproducing the audit
+
+Render any run with `--out-dir DIR`; the mapper writes
+`DIR/representative_mapping.csv` (`symbol_id, family, mode,
+primary_index, secondary_index, aux_index, wm1_index, wm2_index,
+source`). Join its index columns against the simulator's
+`--output-row-map` CSV to recover `circ_id`/`pop_id` per symbol, and
+classify with the `pop_id` rule in §2.
+
+- `wm1_index == -1` → the symbol can never render yellow.
+- `primary_index == wm1_index` → the symbol can never render red.
+
+## See also
+
+- `docs/simulation-and-visualization-workflow.tex` — the simulate-to-video workflow
+- `docs/snb15_population_categories.md` — the 30-category population classification
+- `docs/instruction-file-formats.md` — instruction times are timestep indices, `h = 0.1` ms
+- `rnba/schematic_visualization.py` — the base schematic the overlay is drawn on

rnba-0.2.3/docs/simulation-and-visualization-workflow.tex

@@ -0,0 +1,208 @@
+\documentclass[11pt]{article}
+
+\usepackage[margin=1in]{geometry}
+\usepackage{hyperref}
+\usepackage{enumitem}
+\usepackage{listings}
+\usepackage{xcolor}
+
+\lstset{
+  basicstyle=\ttfamily\small,
+  breaklines=true,
+  frame=single,
+  columns=fullflexible,
+  keepspaces=true,
+  showstringspaces=false,
+}
+
+\newcommand{\opt}[1]{\texttt{#1}}
+
+\title{RNBA: From Architecture to Activity Video}
+\author{RNBA documentation}
+\date{}
+
+\begin{document}
+\maketitle
+
+\noindent
+This note describes the two-step workflow that turns an RNBA blackboard
+architecture and an instruction file into a rendered activity-flow video.
+It corresponds to the commands in \texttt{\textasciitilde/NBAExperiments/start}
+and explains every option used there. The example presents the sentence
+\emph{``Sue eats pizza''} to the SNB15 network and renders the resulting
+dynamics.
+
+\section*{Overview}
+
+The workflow has two stages, each a separate command:
+
+\begin{enumerate}[leftmargin=*]
+  \item \textbf{Simulate} with \texttt{rnba-run} (the Python simulator).
+        It reads the architecture and instruction files, integrates the
+        network dynamics, and writes the population traces to CSV.
+  \item \textbf{Visualise} with \texttt{python -m rnba.visualize\_activity\_flow}.
+        It overlays those traces on the canonical SNB15 schematic and
+        renders an MP4 video.
+\end{enumerate}
+
+The stages communicate through the CSV files written in step~1 and read
+back in step~2. All times inside RNBA are integer timestep indices with
+a fixed step $h = 0.1$~ms.
+
+\section*{Environment setup}
+
+\begin{lstlisting}
+python3 -m venv .venv
+source .venv/bin/activate
+\end{lstlisting}
+
+\noindent
+Creates and activates a virtual environment. Install the package into it
+with \texttt{pip install rnba} (version 0.2.2 or later is required for the
+\opt{--workers} option in step~2).
+
+\section*{Step 1: Run the simulation}
+
+\begin{lstlisting}
+rnba-run \
+  --architecture ~/NBAExperiments/Sue_Eats_Pizza/RNBA_arch_SGall_SNB15.txt \
+  --instruction  ~/NBAExperiments/Sue_Eats_Pizza/instruction.txt \
+  --output       ~/NBAExperiments/Sue_Eats_Pizza/RNBA_simulation_output.csv \
+  --output-row-map ~/NBAExperiments/Sue_Eats_Pizza/RNBA_row_map.csv \
+  --output-named \
+  --output-inputs ~/NBAExperiments/Sue_Eats_Pizza/inputs.csv
+\end{lstlisting}
+
+\begin{description}[leftmargin=0pt,style=nextline]
+  \item[\opt{--architecture} FILE]
+    The blackboard architecture (here the SNB15 configuration). It
+    describes every population and its wiring; \texttt{rnba-run} builds
+    the network from it. Required.
+
+  \item[\opt{--instruction} FILE]
+    The instruction file giving the timings at which external inputs
+    (word, gating, and binding populations) switch on and off. It uses
+    the unified instruction format and is parsed strictly. The
+    simulation duration is derived automatically from the schedule (plus
+    a settling tail; see \opt{--tail-steps}).
+
+  \item[\opt{--output} FILE]
+    Destination CSV for the population traces: one row per timestep, one
+    column per population, with a \texttt{time\_ms} first column.
+
+  \item[\opt{--output-row-map} FILE]
+    Writes the mapping between CSV column (row index) and population
+    metadata (\texttt{pop\_id}, type, circuit, etc.). The visualiser and
+    other downstream tools use it to know which column is which
+    population.
+
+  \item[\opt{--output-named}]
+    Also writes a second copy of the trace CSV whose column headers are
+    the human-readable \texttt{pop\_id[row]} names rather than bare row
+    indices. With no argument it defaults to \texttt{<output>\_named.csv}.
+    Because \opt{--output-inputs} is also given, a named copy of the
+    input traces is written alongside it as well.
+
+  \item[\opt{--output-inputs} FILE]
+    Writes the external input traces (the driven activation of the input
+    populations) to a separate CSV. Step~2 reads this to display the
+    inputs in the video.
+\end{description}
+
+\paragraph{Duration.}
+No duration flag is passed, so the length is computed from the
+instruction schedule plus \opt{--tail-steps} (default 500 settling
+steps). Override with \opt{--t-end} MS or \opt{--n-steps} N if a fixed
+length is needed.
+
+\section*{Step 2: Render the activity-flow video}
+
+\begin{lstlisting}
+python -m rnba.visualize_activity_flow \
+  --dpi 75 --workers 6 \
+  --architecture RNBA_arch_SGall_SNB15.txt \
+  --trace-csv    RNBA_simulation_output.csv \
+  --inputs-csv   inputs.csv \
+  --out-dir      activity_flow_out \
+  --render-video \
+  --frames-dir   activity_flow_out/frames \
+  --video-out    Sue_Eats_Pizza_activity.mp4 \
+  --fps 25 --step-ms 1.0
+\end{lstlisting}
+
+\noindent
+This command is run from inside the \texttt{Sue\_Eats\_Pizza} directory,
+so the file arguments are relative paths referring to the outputs of
+step~1.
+
+\begin{description}[leftmargin=0pt,style=nextline]
+  \item[\opt{--dpi} 75]
+    Rendering resolution. The figure canvas is $13\times18$ inches, so
+    \opt{--dpi}~75 yields $975\times1350$-pixel frames. Lower DPI gives
+    smaller files but only marginally faster rendering, because the cost
+    is dominated by drawing the schematic rather than rasterising pixels.
+
+  \item[\opt{--workers} 6]
+    Number of parallel worker processes for frame rendering. Each worker
+    builds its own copy of the base schematic and renders a share of the
+    frames; the output is identical to a sequential run. Choose a value
+    up to the CPU core count (each worker holds a full figure, so watch
+    memory). Requires rnba 0.2.2 or later.
+
+  \item[\opt{--architecture} FILE]
+    The same architecture file as step~1. The visualiser uses it to lay
+    out the schematic and to map trace columns onto schematic symbols.
+
+  \item[\opt{--trace-csv} FILE]
+    The population-trace CSV produced by step~1 (\opt{--output}). Its
+    values drive the brightness and edge intensity of the overlay.
+
+  \item[\opt{--inputs-csv} FILE]
+    The external-input trace CSV produced by step~1
+    (\opt{--output-inputs}). Merged into each frame so the driving
+    inputs are shown alongside the network activity.
+
+  \item[\opt{--out-dir} DIR]
+    Output directory for the renderer's auxiliary artifacts (symbol
+    catalogue, representative mapping, and the single-frame preview PNG).
+
+  \item[\opt{--render-video}]
+    Enables the full video pass. Without it the tool writes only a
+    single static preview frame. With it, frames are sampled across the
+    whole trace and assembled into an MP4 with \texttt{ffmpeg} (which
+    must be on \texttt{PATH}).
+
+  \item[\opt{--frames-dir} DIR]
+    Directory for the individual PNG frames. Any existing
+    \texttt{frame\_*.png} files there are cleared first, then one PNG is
+    written per sampled timestep before muxing.
+
+  \item[\opt{--video-out} FILE]
+    Path of the final MP4. Encoded with \texttt{libx264} / \texttt{yuv444p}
+    for broad player compatibility.
+
+  \item[\opt{--fps} 25]
+    Frames per second of the output video (playback rate).
+
+  \item[\opt{--step-ms} 1.0]
+    Sampling stride over the trace, in milliseconds: one frame is
+    rendered per 1~ms of simulated time. Smaller values give smoother,
+    longer videos with more frames; larger values render faster.
+\end{description}
+
+\paragraph{Result.}
+\texttt{Sue\_Eats\_Pizza\_activity.mp4} shows the activity flowing
+through the blackboard as the sentence is presented, with the auxiliary
+CSVs and preview PNG left in \texttt{activity\_flow\_out/} for
+inspection.
+
+\section*{Related documentation}
+
+\begin{itemize}[leftmargin=*]
+  \item Instruction file format: \texttt{docs/instruction-file-formats.md}
+  \item Bindings file format: \texttt{docs/bindings-file-format.md}
+  \item Full option lists: \texttt{rnba-run -{}-help} and
+        \texttt{python -m rnba.visualize\_activity\_flow -{}-help}
+\end{itemize}
+
+\end{document}