rnba 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: rnba
-Version: 0.2.0
+Version: 0.2.2
 Summary: Recurrent Neural Blackboard Architecture - a simulation framework for neuro-cognitive modelling.
 Author-Email: RNBA Contributors <m.dekamps@leeds.ac.uk>
 License: MIT
@@ -74,8 +74,8 @@ Plotting and visualization extras: `pip install "rnba[viz]"` (matplotlib + graph
 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`).
+2. an **instruction file** giving the timings at which populations are switched on and off — word inputs, gating populations, etc. Both simulators read the unified instruction format (legacy QA and SGall files are valid subsets) with strict parsing; it is 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 format is documented in [docs/bindings-file-format.md](docs/bindings-file-format.md).
 
 The output is a CSV with one row per timestep (`h = 0.1` ms) and one column per population.
 
@@ -161,6 +161,10 @@ python -m rnba.visualize_activity_flow \
   --fps 25 --step-ms 1.0
 ```
 
+To zoom in on the top of the blackboard, add `--first-rows N` (e.g. `--first-rows 5`): the view is cropped to the first N rows and markers are enlarged for legibility, while the layout and trace mapping stay identical to the full 15-row view. This works for both the single-frame preview (`--preview-time-ms`) and full video rendering, and mirrors the `--first-rows` option of the static schematic renderer (see below).
+
+Frame rendering dominates the runtime. Pass `--workers N` to render frames across N processes (each holds its own copy of the base schematic); output is identical to a sequential run. `--dpi` trades resolution for size but has little effect on speed, since most per-frame cost is drawing the schematic rather than rasterising pixels.
+
 See `python -m rnba.visualize_activity_flow --help` for the full option set (codec, styling, frame selection).
 
 ## Quick Start: Replicating the QA Simulation
@@ -222,10 +226,11 @@ RNBA uses **two complementary naming schemes**:
 ## 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
+- 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/)
+- Design notes: [docs/design/](docs/design/)
+- Circuit library design and implementation status: [docs/design/CIRCUIT_LIBRARY_DESIGN.md](docs/design/CIRCUIT_LIBRARY_DESIGN.md)
 
 ### Circuit Factory Functions
 

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

@@ -37,8 +37,8 @@ Plotting and visualization extras: `pip install "rnba[viz]"` (matplotlib + graph
 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`).
+2. an **instruction file** giving the timings at which populations are switched on and off — word inputs, gating populations, etc. Both simulators read the unified instruction format (legacy QA and SGall files are valid subsets) with strict parsing; it is 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 format is documented in [docs/bindings-file-format.md](docs/bindings-file-format.md).
 
 The output is a CSV with one row per timestep (`h = 0.1` ms) and one column per population.
 
@@ -124,6 +124,10 @@ python -m rnba.visualize_activity_flow \
   --fps 25 --step-ms 1.0
 ```
 
+To zoom in on the top of the blackboard, add `--first-rows N` (e.g. `--first-rows 5`): the view is cropped to the first N rows and markers are enlarged for legibility, while the layout and trace mapping stay identical to the full 15-row view. This works for both the single-frame preview (`--preview-time-ms`) and full video rendering, and mirrors the `--first-rows` option of the static schematic renderer (see below).
+
+Frame rendering dominates the runtime. Pass `--workers N` to render frames across N processes (each holds its own copy of the base schematic); output is identical to a sequential run. `--dpi` trades resolution for size but has little effect on speed, since most per-frame cost is drawing the schematic rather than rasterising pixels.
+
 See `python -m rnba.visualize_activity_flow --help` for the full option set (codec, styling, frame selection).
 
 ## Quick Start: Replicating the QA Simulation
@@ -185,10 +189,11 @@ RNBA uses **two complementary naming schemes**:
 ## 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
+- 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/)
+- Design notes: [docs/design/](docs/design/)
+- Circuit library design and implementation status: [docs/design/CIRCUIT_LIBRARY_DESIGN.md](docs/design/CIRCUIT_LIBRARY_DESIGN.md)
 
 ### Circuit Factory Functions
 

{rnba-0.2.0 → rnba-0.2.2}/cpp-sim/include/parser.hpp

@@ -17,42 +17,23 @@ struct ScheduleWindow {
     double amplitude;
 };
 
-enum class InstructionFormat {
-    SGall,
-    QA,
-};
-
-struct ParsedInstructionSchedule {
-    InstructionFormat format;
-    std::map<std::string, std::vector<ScheduleWindow>> schedule;
-};
-
 /**
- * Parse instruction file (e.g., QA_3NVN_O_success.txt).
+ * Parse an instruction file in the unified format (see
+ * docs/instruction-file-formats.md).  Legacy SGall and QA files are
+ * valid subsets and parse unchanged.
+ *
+ * Parsing is strict: unknown commands, wrong arities, out-of-range word
+ * indices, misplaced directives and degenerate windows all throw
+ * std::runtime_error with the offending file/line.
+ *
+ * Times in the file are integer timestep indices (multiply by h=0.1 ms).
  * Returns map from pop_id → list of schedule windows.
- * 
- * File format (line-oriented):
- *   t_start t_end pop_id
- *   ...
- * where times are in timestep indices (multiply by h=0.1 ms).
  */
 std::map<std::string, std::vector<ScheduleWindow>>
 parse_instruction_file(
     const std::string& filepath,
     double h = 0.1,
-    double amplitude = 100.0,
-    bool strict = false
-);
-
-/**
- * Parse instruction file and return both detected format and schedule.
- */
-ParsedInstructionSchedule
-parse_instruction_file_with_format(
-    const std::string& filepath,
-    double h = 0.1,
-    double amplitude = 100.0,
-    bool strict = false
+    double amplitude = 100.0
 );
 
 /**

{rnba-0.2.0 → rnba-0.2.2}/cpp-sim/src/main.cpp

@@ -30,7 +30,8 @@ void print_usage(const char* prog) {
         << "      --t-end N*0.1. Mutually exclusive with --t-end.\n\n"
         << "Optional arguments:\n"
         << "  --instructions FILE\n"
-        << "      QA instruction file in the existing RNBA text format. If provided,\n"
+        << "      Instruction file in the unified RNBA text format (legacy QA and\n"
+        << "      SGall files are valid subsets; parsed strictly). If provided,\n"
         << "      instruction windows are mapped onto model input populations.\n"
         << "  --bindings FILE\n"
         << "      WM bindings file in the existing RNBA text format. If provided,\n"
@@ -168,18 +169,13 @@ int main(int argc, char* argv[]) {
         // Parse and apply instruction schedule
         if (!instr_file.empty()) {
             std::cout << "Parsing instruction file: " << instr_file << "\n";
-            auto parsed = rnba::parse_instruction_file_with_format(instr_file, 0.1, 100.0, true);
-
-            if (parsed.format == rnba::InstructionFormat::SGall) {
-                std::cout << "  Detected instruction format: SGall (drive)\n";
-            } else {
-                std::cout << "  Detected instruction format: QA (drive)\n";
-            }
+            std::cout << "  Instruction format: unified (strict parsing)\n";
+            const auto schedule = rnba::parse_instruction_file(instr_file, 0.1, 100.0);
 
             int applied = 0;
             int missing = 0;
 
-            for (const auto& kv : parsed.schedule) {
+            for (const auto& kv : schedule) {
                 const auto it = input_name_to_idx.find(kv.first);
                 if (it == input_name_to_idx.end()) {
                     missing += 1;

rnba-0.2.2/cpp-sim/src/parser.cpp

@@ -0,0 +1,366 @@
+#include "parser.hpp"
+#include <algorithm>
+#include <fstream>
+#include <iostream>
+#include <map>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace rnba {
+
+namespace {
+
+std::vector<std::string> split_ws(const std::string& s) {
+    std::istringstream iss(s);
+    std::vector<std::string> out;
+    std::string tok;
+    while (iss >> tok) {
+        out.push_back(tok);
+    }
+    return out;
+}
+
+std::unordered_map<std::string, std::string> build_command_map() {
+    std::unordered_map<std::string, std::string> m;
+    m["Word_inhib"] = "EX0a_inhib_W_all";
+
+    const std::vector<std::string> lma_short = {
+        "Adj", "Adv", "C", "Co", "Det", "N", "P", "Pr", "V"
+    };
+    const std::vector<std::string> lma_full = {
+        "Adjective", "Adverb", "Clause", "Coordinator", "Determiner",
+        "Noun", "Preposition", "Pronoun", "Verb"
+    };
+    for (size_t i = 0; i < lma_short.size(); ++i) {
+        const std::string& sh = lma_short[i];
+        const std::string& fu = lma_full[i];
+        m[fu] = "EX2_Bgate_W_" + sh;
+        m[fu + "_H"] = "EX3H_Gate_" + sh + "_H";
+        m[fu + "_D"] = "EX3D_Gate_" + sh + "_D";
+        m["CMtoW_" + fu + "_H"] = "EX8H_LMA_out_" + sh + "_H";
+        m["CMtoW_" + fu + "_D"] = "EX8D_LMA_out_" + sh + "_D";
+        m[fu + "_inhib"] = "EX0_inhib_" + sh;
+    }
+
+    const std::vector<std::string> sg_names = {
+        "SG1Verb", "SG2Subject", "SG3Object", "SG4Det", "SG5Compl",
+        "SG6Mod", "SG7Adjunct", "SG8PC", "SG9Ex_Mod", "SG10Coord", "SG11GAP"
+    };
+    for (const auto& sg : sg_names) {
+        m["binding_" + sg + "_H"] = "EX4H_Bgate_LMA_" + sg + "_H";
+        m["binding_" + sg + "_D"] = "EX4D_Bgate_LMA_" + sg + "_D";
+        m[sg + "_H"] = "EX6H_Gate_" + sg + "_CM_H";
+        m[sg + "_D"] = "EX6D_Gate_" + sg + "_CM_D";
+        m[sg + "_W_H"] = "EX5H_Gate_" + sg + "_W_H";
+        m[sg + "_W_D"] = "EX5D_Gate_" + sg + "_W_D";
+        m["inhibcomp_" + sg + "_H"] = "EX7H_SG_comp_inhib_" + sg + "_H";
+        m["inhibcomp_" + sg + "_D"] = "EX7D_SG_comp_inhib_" + sg + "_D";
+    }
+
+    return m;
+}
+
+const std::unordered_map<std::string, std::string> kCommandMap = build_command_map();
+
+constexpr const char* kFormatDirectiveName = "rnba-instructions";
+constexpr int kFormatDirectiveVersion = 1;
+
+[[noreturn]] void parse_error(
+    const std::string& filepath,
+    int line_no,
+    const std::string& message
+) {
+    throw std::runtime_error(
+        filepath + ":" + std::to_string(line_no) + ": " + message
+    );
+}
+
+int parse_int(
+    const std::string& token,
+    const std::string& filepath,
+    int line_no,
+    const std::string& what
+) {
+    try {
+        size_t consumed = 0;
+        const int value = std::stoi(token, &consumed);
+        if (consumed != token.size()) {
+            parse_error(filepath, line_no,
+                        what + " must be an integer, got '" + token + "'");
+        }
+        return value;
+    } catch (const std::invalid_argument&) {
+        parse_error(filepath, line_no,
+                    what + " must be an integer, got '" + token + "'");
+    } catch (const std::out_of_range&) {
+        parse_error(filepath, line_no,
+                    what + " out of integer range: '" + token + "'");
+    }
+}
+
+}  // namespace
+
+// ─── Public Parser Interface ─────────────────────────────────────────────────
+// Unified strict instruction parser (see docs/instruction-file-formats.md).
+// Legacy SGall and QA files are valid subsets and parse unchanged; word
+// windows without an explicit end take their length from fixed_time.
+std::map<std::string, std::vector<ScheduleWindow>>
+parse_instruction_file(
+    const std::string& filepath,
+    double h,
+    double amplitude
+) {
+    std::map<std::string, std::vector<ScheduleWindow>> result;
+
+    std::ifstream in(filepath);
+    if (!in) {
+        throw std::runtime_error("Failed to open instruction file: " + filepath);
+    }
+
+    bool have_word_list = false;
+    std::vector<std::string> word_list;
+    bool have_fixed_time = false;
+    int fixed_time = 0;
+    int step_size = 0;
+    bool seen_command = false;
+    bool seen_format = false;
+    bool seen_fixed_time = false;
+    bool seen_num_of_words = false;
+
+    std::string raw_line;
+    int line_no = 0;
+    while (std::getline(in, raw_line)) {
+        line_no += 1;
+        const auto parts = split_ws(raw_line);
+        if (parts.empty()) {
+            continue;
+        }
+        // Comments occupy whole lines; leading whitespace is allowed.
+        if (!parts[0].empty() && parts[0][0] == '#') {
+            continue;
+        }
+
+        const std::string& cmd = parts[0];
+
+        if (cmd == "format" || cmd == "fixed_time" || cmd == "Num_of_words") {
+            if (seen_command) {
+                parse_error(filepath, line_no,
+                            "directive '" + cmd +
+                            "' must appear before the first command");
+            }
+            bool& seen_flag = (cmd == "format") ? seen_format
+                            : (cmd == "fixed_time") ? seen_fixed_time
+                            : seen_num_of_words;
+            if (seen_flag) {
+                parse_error(filepath, line_no, "duplicate directive '" + cmd + "'");
+            }
+            seen_flag = true;
+
+            if (cmd == "format") {
+                if (parts.size() != 3 || parts[1] != kFormatDirectiveName) {
+                    parse_error(filepath, line_no,
+                                std::string("format directive must read 'format ") +
+                                kFormatDirectiveName + " " +
+                                std::to_string(kFormatDirectiveVersion) + "'");
+                }
+                const int version = parse_int(parts[2], filepath, line_no, "format version");
+                if (version != kFormatDirectiveVersion) {
+                    parse_error(filepath, line_no,
+                                "unsupported format version " + std::to_string(version) +
+                                " (supported: " + std::to_string(kFormatDirectiveVersion) + ")");
+                }
+            } else if (cmd == "fixed_time") {
+                if (parts.size() != 2) {
+                    parse_error(filepath, line_no, "fixed_time takes exactly one value");
+                }
+                fixed_time = parse_int(parts[1], filepath, line_no, "fixed_time");
+                if (fixed_time <= 0) {
+                    parse_error(filepath, line_no, "fixed_time must be positive");
+                }
+                have_fixed_time = true;
+            } else {  // Num_of_words
+                if (parts.size() != 2) {
+                    parse_error(filepath, line_no, "Num_of_words takes exactly one value");
+                }
+                const int n_words = parse_int(parts[1], filepath, line_no, "Num_of_words");
+                if (n_words < 0) {
+                    parse_error(filepath, line_no, "Num_of_words must be non-negative");
+                }
+                word_list.clear();
+                word_list.reserve(static_cast<size_t>(n_words));
+                for (int k = 0; k < n_words; ++k) {
+                    word_list.push_back("EX1_input_W" + std::to_string(k));
+                }
+                have_word_list = true;
+            }
+            continue;
+        }
+
+        seen_command = true;
+
+        int start = 0;
+        int end = 0;
+        std::string pop_id;
+
+        if (cmd == "Word") {
+            if (!have_word_list) {
+                parse_error(filepath, line_no, "'Word' encountered before Num_of_words");
+            }
+            int word_idx = 0;
+            if (parts.size() == 3) {
+                if (!have_fixed_time) {
+                    parse_error(filepath, line_no,
+                                "2-argument 'Word' requires a fixed_time directive; "
+                                "use 'Word <rel_start> <rel_end> <word_idx>' for an explicit end");
+                }
+                const int rel_start = parse_int(parts[1], filepath, line_no, "rel_start");
+                word_idx = parse_int(parts[2], filepath, line_no, "word index");
+                start = step_size + rel_start;
+                step_size = start;
+                end = start + fixed_time;
+            } else if (parts.size() == 4) {
+                const int rel_start = parse_int(parts[1], filepath, line_no, "rel_start");
+                const int rel_end = parse_int(parts[2], filepath, line_no, "rel_end");
+                word_idx = parse_int(parts[3], filepath, line_no, "word index");
+                start = step_size + rel_start;
+                step_size = start;
+                end = start + rel_end;
+            } else {
+                parse_error(filepath, line_no,
+                            "'Word' takes 2 arguments (rel_start word_idx, with fixed_time) "
+                            "or 3 (rel_start rel_end word_idx)");
+            }
+            if (word_idx < 0 || word_idx >= static_cast<int>(word_list.size())) {
+                parse_error(filepath, line_no,
+                            "word index " + std::to_string(word_idx) +
+                            " out of range (Num_of_words = " +
+                            std::to_string(word_list.size()) + ")");
+            }
+            pop_id = word_list[static_cast<size_t>(word_idx)];
+        } else {
+            const auto it = kCommandMap.find(cmd);
+            if (it == kCommandMap.end()) {
+                parse_error(filepath, line_no, "unknown command '" + cmd + "'");
+            }
+            if (parts.size() == 2) {
+                if (!have_fixed_time) {
+                    parse_error(filepath, line_no,
+                                "1-argument '" + cmd + "' requires a fixed_time directive; "
+                                "use '" + cmd + " <rel_start> <rel_end>' for an explicit end");
+                }
+                start = step_size + parse_int(parts[1], filepath, line_no, "rel_start");
+                end = start + fixed_time;
+            } else if (parts.size() == 3) {
+                start = step_size + parse_int(parts[1], filepath, line_no, "rel_start");
+                end = step_size + parse_int(parts[2], filepath, line_no, "rel_end");
+            } else {
+                parse_error(filepath, line_no,
+                            "'" + cmd + "' takes 1 argument (rel_start, with fixed_time) "
+                            "or 2 (rel_start rel_end)");
+            }
+            pop_id = it->second;
+        }
+
+        if (start < 0) {
+            parse_error(filepath, line_no,
+                        "window start " + std::to_string(start) + " is negative");
+        }
+        if (end <= start) {
+            parse_error(filepath, line_no,
+                        "window end " + std::to_string(end) +
+                        " does not lie after start " + std::to_string(start));
+        }
+        result[pop_id].push_back(ScheduleWindow{start * h, end * h, amplitude});
+    }
+
+    return result;
+}
+
+std::vector<int>
+parse_bindings_file(const std::string& filepath) {
+    std::vector<int> result;
+
+    std::ifstream in(filepath);
+    if (!in) {
+        throw std::runtime_error("Failed to open bindings file: " + filepath);
+    }
+
+    std::string raw_line;
+    while (std::getline(in, raw_line)) {
+        const auto parts = split_ws(raw_line);
+        if (parts.empty()) {
+            continue;
+        }
+        // Skip comments and non-data headings.
+        if (!parts[0].empty() && parts[0][0] == '#') {
+            continue;
+        }
+
+        // Data lines begin with p_index as first integer token.
+        // Headings like "p_index ..." are skipped by failed stoi.
+        try {
+            const int idx = std::stoi(parts[0]);
+            if (idx < 0) {
+                throw std::runtime_error("Negative binding index encountered: " + std::to_string(idx));
+            }
+            result.push_back(idx);
+        } catch (const std::invalid_argument&) {
+            // Ignore non-numeric first token lines.
+            continue;
+        } catch (const std::out_of_range&) {
+            throw std::runtime_error("Binding index out of range in line: " + raw_line);
+        }
+    }
+
+    return result;
+}
+
+std::function<double(double)>
+make_piecewise_activation(const std::vector<ScheduleWindow>& windows) {
+    return [windows](double t) -> double {
+        for (const auto& win : windows) {
+            if (t >= win.t_start && t <= win.t_end) {
+                return win.amplitude;
+            }
+        }
+        return 0.0;
+    };
+}
+
+std::function<double(double)>
+make_piecewise_activation_legacy_window(
+    const std::vector<ScheduleWindow>& windows,
+    double h
+) {
+    const double eps = std::max(1e-12, 0.1 * h);
+    return [windows, eps](double t) -> double {
+        for (const auto& win : windows) {
+            if ((t - win.t_start) > eps && (win.t_end - t) >= -eps) {
+                return win.amplitude;
+            }
+        }
+        return 0.0;
+    };
+}
+
+std::function<double(double)>
+make_clamp_function(
+    const std::vector<int>& clamped_nodes,
+    double t_start,
+    double t_end,
+    double value
+) {
+    (void)clamped_nodes;
+    const double eps = 1e-12;
+    return [t_start, t_end, value, eps](double t) -> double {
+        if (t + eps >= t_start && t <= t_end + eps) {
+            return value;
+        }
+        return 0.0;
+    };
+}
+
+}  // namespace rnba