rnba 0.1.0__py3-none-win_amd64.whl

rnba/__init__.py

@@ -0,0 +1,23 @@
+"""RNBA package
+
+Simple package with a greet() helper used in tests and CLI.
+"""
+
+__version__ = "0.1.0"
+
+
+def greet(name: str = "RNBA") -> str:
+    """Return a greeting for `name`."""
+    return f"Hello, {name}!"
+
+
+from .architecture import load_architecture, apply_instruction_schedule, apply_bindings
+
+# Try importing visualization module if graphviz is available
+try:
+    from .visualize import visualize_network, visualize_circuit_template
+    __all__ = ['greet', 'load_architecture', 'apply_instruction_schedule', 'apply_bindings',
+               'visualize_network', 'visualize_circuit_template']
+except ImportError:
+    # graphviz not installed, visualization not available
+    __all__ = ['greet', 'load_architecture', 'apply_instruction_schedule', 'apply_bindings']

rnba/_sim.py

@@ -0,0 +1,57 @@
+"""Locate and run the bundled ``rnba-sim`` C++ simulator executable.
+
+Wheel installs ship the compiled binary in ``rnba/_bin/``. Development
+checkouts fall back to the CMake build tree (``cpp-sim/build/``) and
+finally to ``PATH``.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from importlib.resources import files
+from pathlib import Path
+from typing import Optional, Sequence
+
+_EXE_NAME = "rnba-sim.exe" if os.name == "nt" else "rnba-sim"
+
+
+def sim_executable() -> str:
+    """Return the path to the ``rnba-sim`` executable.
+
+    Raises FileNotFoundError if no executable can be located.
+    """
+    bundled = Path(str(files("rnba"))) / "_bin" / _EXE_NAME
+    if bundled.is_file():
+        return str(bundled)
+
+    dev_build = Path(__file__).resolve().parent.parent / "cpp-sim" / "build" / _EXE_NAME
+    if dev_build.is_file():
+        return str(dev_build)
+
+    on_path = shutil.which(_EXE_NAME)
+    if on_path:
+        return on_path
+
+    raise FileNotFoundError(
+        "rnba-sim executable not found. Install the rnba wheel (which bundles "
+        "it), or build it from a source checkout with: "
+        "cmake -B cpp-sim/build cpp-sim && cmake --build cpp-sim/build"
+    )
+
+
+def run_sim(args: Sequence[str], **subprocess_kwargs) -> subprocess.CompletedProcess:
+    """Run ``rnba-sim`` with ``args`` and return the completed process."""
+    return subprocess.run([sim_executable(), *args], **subprocess_kwargs)
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Console entry point forwarding to the bundled executable."""
+    args = list(sys.argv[1:] if argv is None else argv)
+    return subprocess.call([sim_executable(), *args])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rnba/architecture.py

@@ -0,0 +1,491 @@
+"""Load an RNBA architecture text file into a Network.
+
+Parses the row-based architecture format produced by the NBA build tools
+and returns a fully wired Network where:
+
+- Normal populations become Node objects.
+- External populations become Input objects with dormant activation
+  (``lambda t: 0.0``).  Use :func:`apply_instruction_schedule` to set
+  activation schedules, and :func:`apply_bindings` to register WM
+  clamps.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Tuple, Union
+
+from rnba.network import Network
+from rnba.nodes import Node
+from rnba.inputs import Input
+from rnba.constants import (
+    EXCITATORY_CON_TYPES as _EXCITATORY_CON_TYPES,
+    SIGMOID_PARAMS,
+    TAU_E,
+    TAU_I,
+    W_ALL,
+    WEIGHT_SCALE as _WEIGHT_SCALE,
+    WC_COUPLING_PARAMS,
+)
+
+
+def load_architecture(
+    filepath: Union[str, Path],
+    weight: float = W_ALL,
+    tau_E: float = TAU_E,
+    tau_I: float = TAU_I,
+) -> Network:
+    """Parse an architecture file and build a ready-to-schedule Network.
+
+    Parameters
+    ----------
+    filepath : str or Path
+        Path to an ``RNBA_arch_SGall_SNB*.txt`` file.
+    weight : float, optional
+        Base connection weight (default 0.2, the ``w_all`` used in the
+        original simulation script).
+    tau_E : float, optional
+        Time constant for excitatory populations (default 2.5 ms,
+        matching ``1/0.4`` from ``pop_module.c``).
+    tau_I : float, optional
+        Time constant for inhibitory populations (default 1.25 ms,
+        matching ``1/0.8`` from ``pop_module.c``).
+
+    Returns
+    -------
+    Network
+        A Network with all internal wiring complete.  External inputs
+        have ``activation = lambda t: 0.0`` — set their activation
+        functions before calling ``simulate()``.
+
+    Raises
+    ------
+    FileNotFoundError
+        If *filepath* does not exist.
+    ValueError
+        If the file cannot be parsed or has inconsistent row counts.
+    """
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"Architecture file not found: {filepath}")
+
+    # ------------------------------------------------------------------
+    # 1. Parse
+    # ------------------------------------------------------------------
+    rows = []  # one dict per population row
+    expected_len = None
+
+    with open(filepath) as fh:
+        for raw_line in fh:
+            line = raw_line.strip()
+            if not line:
+                continue
+
+            # Header line: "lenlist= 16298"
+            if line.startswith("lenlist="):
+                expected_len = int(line.split("=")[1])
+                continue
+
+            # Data rows start with a digit (the p_indx column)
+            if not line[0].isdigit():
+                continue
+
+            parts = line.split()
+            if len(parts) < 8:
+                continue
+
+            rows.append({
+                "index": int(parts[0]),
+                "con_typ": parts[1],
+                "pop_typ": parts[2],
+                "pop_id": parts[3],
+                "circ_id": parts[4],
+                "h_row": parts[5],
+                "d_row": parts[6],
+                "mat_id": parts[7],
+                "connection_input": [int(tok) for tok in parts[8:] if tok.isdigit()],
+            })
+
+    if expected_len is not None and len(rows) != expected_len:
+        raise ValueError(
+            f"Expected {expected_len} rows (from lenlist header) but parsed {len(rows)}"
+        )
+
+    # ------------------------------------------------------------------
+    # 2. Create population objects
+    # ------------------------------------------------------------------
+    # Index-ordered lists so row indices stay valid for connection wiring.
+    #
+    # Normal pop_ids are NOT unique (e.g. "GC_start_G1" appears 2745×
+    # across different circuit instances).  External pop_ids ARE unique.
+    # We therefore use the row index as the Node name for normals, and
+    # the pop_id as the Input name for externals.
+    pop_objects = []          # Node | Input, ordered by architecture index
+    pop_is_node = []          # True if Node, False if Input
+    metadata: Dict[str, dict] = {}
+
+    _zero = lambda t: 0.0  # noqa: E731  — shared dormant activation
+
+    for row in rows:
+        idx = row["index"]
+        pid = row["pop_id"]
+
+        if row["pop_typ"] == "normal":
+            # Name by row index — guarantees uniqueness.
+            # Assign tau based on con_typ: excitatory vs inhibitory.
+            is_excit = row["con_typ"] in _EXCITATORY_CON_TYPES
+            tau = tau_E if is_excit else tau_I
+            obj = Node(str(idx), tau=tau, is_excitatory=is_excit)
+            pop_is_node.append(True)
+        else:
+            # External pop_ids are unique; use them directly so callers
+            # can look them up by descriptive name.
+            obj = Input(pid, _zero)
+            pop_is_node.append(False)
+
+        pop_objects.append(obj)
+        metadata[str(idx)] = {
+            "index": idx,
+            "pop_id": pid,
+            "con_typ": row["con_typ"],
+            "pop_typ": row["pop_typ"],
+            "circ_id": row["circ_id"],
+            "h_row": row["h_row"],
+            "d_row": row["d_row"],
+            "mat_id": row["mat_id"],
+        }
+
+    # ------------------------------------------------------------------
+    # 3. Register in Network (build phase)
+    # ------------------------------------------------------------------
+    net = Network(sigmoid_params=SIGMOID_PARAMS, wc_coupling=WC_COUPLING_PARAMS)
+
+    for obj, is_node in zip(pop_objects, pop_is_node):
+        if is_node:
+            net.add_node(obj)
+        else:
+            net.add_input(obj)
+
+    # ------------------------------------------------------------------
+    # 4. Wire connections (connect phase — triggers __MapNodes on first call)
+    # ------------------------------------------------------------------
+    for row in rows:
+        if row["pop_typ"] != "normal":
+            continue  # external pops are sources only, never targets
+
+        target_name = str(row["index"])
+
+        for src_idx in row["connection_input"]:
+            src_row = rows[src_idx]
+            src_con_typ = src_row["con_typ"]
+
+            scale = _WEIGHT_SCALE.get(src_con_typ)
+            if scale is None:
+                raise ValueError(
+                    f"Unknown connection type '{src_con_typ}' on population "
+                    f"{src_idx} ({src_row['pop_id']})"
+                )
+            w = weight * scale
+
+            if src_row["pop_typ"] == "normal":
+                net.ConnectNodeNode(str(src_idx), target_name, w)
+            else:
+                net.ConnectInputNode(src_row["pop_id"], target_name, w)
+
+    # Attach metadata for downstream use (visualisation, debugging).
+    net.population_metadata = metadata
+
+    return net
+
+
+# ======================================================================
+# Instruction-file command → external pop_id mapping
+# ======================================================================
+
+_LMA_SHORT = ['Adj', 'Adv', 'C', 'Co', 'Det', 'N', 'P', 'Pr', 'V']
+_LMA_FULL = [
+    'Adjective', 'Adverb', 'Clause', 'Coordinator', 'Determiner',
+    'Noun', 'Preposition', 'Pronoun', 'Verb',
+]
+_SG_NAMES = [
+    'SG1Verb', 'SG2Subject', 'SG3Object', 'SG4Det', 'SG5Compl',
+    'SG6Mod', 'SG7Adjunct', 'SG8PC', 'SG9Ex_Mod', 'SG10Coord', 'SG11GAP',
+]
+
+
+def _build_command_map() -> Dict[str, str]:
+    """Return a mapping from instruction-file command → external pop_id."""
+    m: Dict[str, str] = {}
+    m['Word_inhib'] = 'EX0a_inhib_W_all'
+
+    for short, full in zip(_LMA_SHORT, _LMA_FULL):
+        m[full] = f'EX2_Bgate_W_{short}'
+        m[f'{full}_H'] = f'EX3H_Gate_{short}_H'
+        m[f'{full}_D'] = f'EX3D_Gate_{short}_D'
+        m[f'CMtoW_{full}_H'] = f'EX8H_LMA_out_{short}_H'
+        m[f'CMtoW_{full}_D'] = f'EX8D_LMA_out_{short}_D'
+        m[f'{full}_inhib'] = f'EX0_inhib_{short}'
+
+    for sg in _SG_NAMES:
+        m[f'binding_{sg}_H'] = f'EX4H_Bgate_LMA_{sg}_H'
+        m[f'binding_{sg}_D'] = f'EX4D_Bgate_LMA_{sg}_D'
+        m[f'{sg}_H'] = f'EX6H_Gate_{sg}_CM_H'
+        m[f'{sg}_D'] = f'EX6D_Gate_{sg}_CM_D'
+        m[f'{sg}_W_H'] = f'EX5H_Gate_{sg}_W_H'
+        m[f'{sg}_W_D'] = f'EX5D_Gate_{sg}_W_D'
+        m[f'inhibcomp_{sg}_H'] = f'EX7H_SG_comp_inhib_{sg}_H'
+        m[f'inhibcomp_{sg}_D'] = f'EX7D_SG_comp_inhib_{sg}_D'
+
+    return m
+
+
+_COMMAND_MAP = _build_command_map()
+
+
+# ======================================================================
+# Instruction-file parser
+# ======================================================================
+
+def _parse_instruction_file(
+    filepath: Path,
+) -> List[Tuple[int, int, str]]:
+    """Parse a sentence/question instruction file.
+
+    Returns a list of ``(start_time, end_time, external_pop_id)``
+    triples, reproducing the logic of
+    ``NBA24_QA_sentence_input.Sentence_file``.
+    """
+    schedule: List[Tuple[int, int, str]] = []
+    word_list: List[str] = []
+    step_size = 0
+
+    with open(filepath) as fh:
+        for raw_line in fh:
+            parts = raw_line.split()
+            if not parts or raw_line.startswith('#'):
+                continue
+
+            cmd = parts[0]
+
+            if cmd == 'Num_of_words':
+                n_words = int(parts[1])
+                word_list = [f'EX1_input_W{k}' for k in range(n_words)]
+                continue
+
+            if cmd == 'Word':
+                start = step_size + int(parts[1])
+                step_size = start
+                end = step_size + int(parts[2])
+                word_idx = int(parts[3])
+                schedule.append((start, end, word_list[word_idx]))
+                continue
+
+            if cmd in _COMMAND_MAP:
+                start = step_size + int(parts[1])
+                end = step_size + int(parts[2])
+                schedule.append((start, end, _COMMAND_MAP[cmd]))
+
+    return schedule
+
+
+def _make_piecewise_activation(
+    windows: List[Tuple[int, int]],
+    amplitude: float,
+):
+    """Return an activation function that is *amplitude* during any of
+    the given ``[start, end]`` windows and 0.0 otherwise."""
+    sorted_windows = sorted(windows)
+
+    def activation(t):
+        for start, end in sorted_windows:
+            if start <= t <= end:
+                return amplitude
+        return 0.0
+
+    return activation
+
+
+# ======================================================================
+# Public API: apply instruction schedule
+# ======================================================================
+
+def apply_instruction_schedule(
+    net: Network,
+    instruction_file: Union[str, Path],
+    amplitude: float = 100.0,
+    h: float = 0.1,
+) -> None:
+    """Set activation functions on external Inputs from an instruction file.
+
+    Parameters
+    ----------
+    net : Network
+        A network previously created by :func:`load_architecture`.
+    instruction_file : str or Path
+        Path to a sentence/question instruction file (e.g.
+        ``QA_3NVN_O_success.txt``).
+    amplitude : float, optional
+        Activation level during scheduled ON windows (default 100.0).
+    h : float, optional
+        Integration step size in ms (default 0.1, from ``pop_module.c``).
+        Instruction-file times are in timestep indices; multiplying by
+        *h* converts them to milliseconds for ``odeint``.
+    """
+    instruction_file = Path(instruction_file)
+    if not instruction_file.exists():
+        raise FileNotFoundError(
+            f"Instruction file not found: {instruction_file}"
+        )
+
+    schedule = _parse_instruction_file(instruction_file)
+
+    # Group windows by pop_id (a single pop may appear in multiple triples).
+    # Scale timestep indices → ms by multiplying by h.
+    windows: Dict[str, List[Tuple[float, float]]] = defaultdict(list)
+    for start, end, pop_id in schedule:
+        windows[pop_id].append((start * h, end * h))
+
+    for pop_id, wins in windows.items():
+        inp = net.get_input(pop_id)
+        inp.activation_func = _make_piecewise_activation(wins, amplitude)
+
+
+# ======================================================================
+# SGall instruction-file parser (fixed_time format)
+# ======================================================================
+
+def _parse_sgall_instruction_file(
+    filepath: Path,
+) -> List[Tuple[int, int, str]]:
+    """Parse an SGall-format sentence instruction file.
+
+    SGall files use a ``fixed_time`` directive and two-argument ``Word``
+    commands (``Word <offset> <word_idx>``), in contrast to QA files
+    which have explicit start/end times.
+
+    Returns a list of ``(start_time, end_time, external_pop_id)`` triples
+    in the same form as :func:`_parse_instruction_file`.
+    """
+    schedule: List[Tuple[int, int, str]] = []
+    word_list: List[str] = []
+    step_size = 0
+    fixed_time = 0
+
+    with open(filepath) as fh:
+        for raw_line in fh:
+            parts = raw_line.split()
+            if not parts or raw_line.startswith('#'):
+                continue
+
+            cmd = parts[0]
+
+            if cmd == 'fixed_time':
+                fixed_time = int(parts[1])
+            elif cmd == 'Num_of_words':
+                n_words = int(parts[1])
+                word_list = [f'EX1_input_W{k}' for k in range(n_words)]
+            elif cmd == 'Word':
+                start = step_size + int(parts[1])
+                step_size = start
+                end = start + fixed_time
+                word_idx = int(parts[2])
+                schedule.append((start, end, word_list[word_idx]))
+            elif cmd in _COMMAND_MAP:
+                start = step_size + int(parts[1])
+                end = start + fixed_time
+                schedule.append((start, end, _COMMAND_MAP[cmd]))
+
+    return schedule
+
+
+def apply_sgall_instruction_schedule(
+    net: Network,
+    instruction_file: Union[str, Path],
+    amplitude: float = 100.0,
+    h: float = 0.1,
+) -> None:
+    """Set activation functions on external Inputs from an SGall sentence file.
+
+    Equivalent to :func:`apply_instruction_schedule` but handles the
+    SGall fixed-time instruction format (``fixed_time`` directive,
+    two-argument ``Word`` command).
+
+    Parameters
+    ----------
+    net : Network
+        A network previously created by :func:`load_architecture`.
+    instruction_file : str or Path
+        Path to an SGall sentence instruction file (e.g.
+        ``Sentence_2CV.txt``).
+    amplitude : float, optional
+        Activation level during scheduled ON windows (default 100.0).
+    h : float, optional
+        Integration step size in ms (default 0.1). Timestep indices in
+        the file are multiplied by *h* to convert to milliseconds.
+    """
+    instruction_file = Path(instruction_file)
+    if not instruction_file.exists():
+        raise FileNotFoundError(
+            f"Instruction file not found: {instruction_file}"
+        )
+
+    schedule = _parse_sgall_instruction_file(instruction_file)
+
+    windows: Dict[str, List[Tuple[float, float]]] = defaultdict(list)
+    for start, end, pop_id in schedule:
+        windows[pop_id].append((start * h, end * h))
+
+    for pop_id, wins in windows.items():
+        inp = net.get_input(pop_id)
+        inp.activation_func = _make_piecewise_activation(wins, amplitude)
+
+
+# ======================================================================
+# Public API: apply bindings
+# ======================================================================
+
+def _parse_bindings_file(filepath: Path) -> List[int]:
+    """Parse a WM bindings file, returning the list of p_index values."""
+    indices: List[int] = []
+    with open(filepath) as fh:
+        for raw_line in fh:
+            parts = raw_line.split()
+            if parts and parts[0].isdigit():
+                indices.append(int(parts[0]))
+    return indices
+
+
+def apply_bindings(
+    net: Network,
+    bindings_file: Union[str, Path],
+    t_start: float,
+    t_end: float,
+    value: float,
+) -> None:
+    """Register clamps on WM binding populations from a bindings file.
+
+    Parameters
+    ----------
+    net : Network
+        A network previously created by :func:`load_architecture`.
+    bindings_file : str or Path
+        Path to a WM bindings file (e.g.
+        ``RNBA_SGall_SNB15_Bindings_Sentence_3NVN.txt``).
+    t_start : float
+        Start time of the clamp window.
+    t_end : float
+        End time of the clamp window.
+    value : float
+        Activation value to hold during the clamp window.
+    """
+    bindings_file = Path(bindings_file)
+    if not bindings_file.exists():
+        raise FileNotFoundError(
+            f"Bindings file not found: {bindings_file}"
+        )
+
+    indices = _parse_bindings_file(bindings_file)
+    for idx in indices:
+        # Node names in load_architecture are the stringified row index.
+        net.add_clamp(str(idx), t_start, t_end, value)