Implement Converge slice expansion

Author: erosmarcello

Cargo.lock

@@ -7,4 +7,3 @@ version = "0.1.0"
 edition = "2024"
 license = "MIT"
 rust-version = "1.92"
-

Cargo.toml

@@ -54,14 +54,17 @@ cargo test
 cargo run -p converge-cli -- check examples/hello.cv
 cargo run -p converge-cli -- ast   examples/hello.cv
 cargo run -p converge-cli -- cvir  examples/hello.cv
+cargo run -p converge-cli -- sim   examples/poisson.cv
 ```
 
 ## Docs
 
 1. `docs/spec.md` current accepted grammar and validation rules
-2. `docs/references.md` curated anchors for hardware and interchange
-3. `docs/voice.md` writing rules for project docs
-4. `docs/brand.md` logo and asset guidance
+2. `docs/semantics.md` time model and determinism rules
+3. `docs/cvir.md` canonical IR schema and examples
+4. `docs/references.md` curated anchors for hardware and interchange
+5. `docs/voice.md` writing rules for project docs
+6. `docs/brand.md` logo and asset guidance
 
 ## Origin
 

README.md

@@ -11,4 +11,4 @@ path = "src/main.rs"
 
 [dependencies]
 converge-lang = { path = "../converge-lang" }
-
+converge-sim = { path = "../converge-sim" }

crates/converge-cli/Cargo.toml

@@ -4,6 +4,7 @@ use std::path::Path;
 
 use converge_lang::parser::{format_diagnostic, parse_program};
 use converge_lang::validate::validate;
+use converge_sim::simulate;
 
 fn main() {
     let mut args = std::env::args().skip(1);
@@ -13,6 +14,7 @@ fn main() {
         "check" => cmd_check(args),
         "ast" => cmd_ast(args),
         "cvir" => cmd_cvir(args),
+        "sim" => cmd_sim(args),
         "help" | "-h" | "--help" => {
             print_usage();
             std::process::exit(0);
@@ -103,6 +105,66 @@ fn cmd_cvir(mut args: impl Iterator<Item = String>) {
     print!("{}", converge_lang::emit::cvir_json(&program));
 }
 
+fn cmd_sim(mut args: impl Iterator<Item = String>) {
+    let mut file = None;
+    let mut out_path = None;
+
+    while let Some(arg) = args.next() {
+        if arg == "--out" {
+            out_path = args.next();
+        } else if file.is_none() {
+            file = Some(arg);
+        } else {
+            eprintln!("error: unexpected argument `{arg}`\n");
+            print_usage();
+            std::process::exit(2);
+        }
+    }
+
+    let path = match file {
+        Some(p) => p,
+        None => {
+            eprintln!("error: expected a file path\n");
+            print_usage();
+            std::process::exit(2);
+        }
+    };
+
+    let src = read_file(&path);
+    let program = match parse_program(&src) {
+        Ok(p) => p,
+        Err(diag) => {
+            eprintln!("{}", format_diagnostic(&src, &diag));
+            std::process::exit(1);
+        }
+    };
+
+    if let Err(diags) = validate(&program) {
+        for diag in diags {
+            eprintln!("{}", format_diagnostic(&src, &diag));
+        }
+        std::process::exit(1);
+    }
+
+    let summary = match simulate(&program) {
+        Ok(s) => s,
+        Err(err) => {
+            eprintln!("error: {err}");
+            std::process::exit(1);
+        }
+    };
+    let json = converge_sim::summary_json(&summary);
+
+    if let Some(out) = out_path {
+        std::fs::write(&out, json).unwrap_or_else(|e| {
+            eprintln!("error: failed to write `{out}`: {e}");
+            std::process::exit(2);
+        });
+    } else {
+        print!("{json}");
+    }
+}
+
 fn read_file(path: &str) -> String {
     std::fs::read_to_string(Path::new(path)).unwrap_or_else(|e| {
         eprintln!("error: failed to read `{path}`: {e}");
@@ -122,12 +184,14 @@ COMMANDS:
   check   Parse + validate a Converge file
   ast     Print parsed AST (debug)
   cvir    Emit canonical JSON IR (debug)
+  sim     Run deterministic simulator
   help    Show this help
 
 EXAMPLES:
   cargo run -p converge-cli -- check examples/hello.cv
   cargo run -p converge-cli -- ast   examples/hello.cv
   cargo run -p converge-cli -- cvir  examples/hello.cv
+  cargo run -p converge-cli -- sim   examples/poisson.cv
 "
     );
 }

crates/converge-cli/src/main.rs

@@ -0,0 +1,19 @@
+use std::process::Command;
+
+#[test]
+fn sim_cli_runs() {
+    let exe = std::env::var("CARGO_BIN_EXE_converge").unwrap_or_else(|_| {
+        let manifest = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+        manifest
+            .join("../../target/debug/converge")
+            .to_string_lossy()
+            .to_string()
+    });
+    let manifest = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let example = manifest.join("../../examples/poisson.cv");
+    let output = Command::new(exe)
+        .args(["sim", example.to_string_lossy().as_ref()])
+        .output()
+        .expect("run converge sim");
+    assert!(output.status.success());
+}

crates/converge-cli/tests/sim.rs

@@ -16,7 +16,9 @@ pub enum Item {
     Neuron(NeuronDef),
     Layer(LayerDef),
     Connect(ConnectDef),
+    Stimulus(StimulusDef),
     Run(RunStmt),
+    Seed(SeedStmt),
 }
 
 #[derive(Debug, Clone, PartialEq)]
@@ -42,6 +44,24 @@ pub struct ConnectDef {
 #[derive(Debug, Clone, PartialEq)]
 pub struct RunStmt {
     pub duration: Quantity,
+    pub step: Option<Quantity>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct SeedStmt {
+    pub value: u64,
+    pub span: Span,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct StimulusDef {
+    pub layer: Ident,
+    pub model: StimulusModel,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum StimulusModel {
+    Poisson { rate: Quantity },
 }
 
 #[derive(Debug, Clone, PartialEq)]

crates/converge-lang/src/ast.rs

@@ -4,16 +4,32 @@ pub fn cvir_json(program: &Program) -> String {
     let mut w = JsonWriter::new();
     w.obj_begin();
 
+    w.kv_str("cvir_version", "0.2");
+    w.comma_nl();
     w.key("items");
     w.array_begin();
-    for (idx, item) in program.items.iter().enumerate() {
-        if idx != 0 {
+    let seed = program
+        .items
+        .iter()
+        .find_map(|item| match item {
+            Item::Seed(s) => Some(s.value),
+            _ => None,
+        })
+        .unwrap_or(0);
+
+    let mut first = true;
+    for item in program.items.iter() {
+        if matches!(item, Item::Seed(_)) {
+            continue;
+        }
+        if !first {
             w.comma();
         }
+        first = false;
         w.nl();
-        emit_item(&mut w, item);
+        emit_item(&mut w, item, seed);
     }
-    if !program.items.is_empty() {
+    if !first {
         w.nl();
     }
     w.array_end();
@@ -24,7 +40,7 @@ pub fn cvir_json(program: &Program) -> String {
     w.finish()
 }
 
-fn emit_item(w: &mut JsonWriter, item: &Item) {
+fn emit_item(w: &mut JsonWriter, item: &Item, seed: u64) {
     w.obj_begin();
     match item {
         Item::Neuron(d) => {
@@ -54,11 +70,42 @@ fn emit_item(w: &mut JsonWriter, item: &Item) {
             w.key("body");
             emit_assigns(w, &d.body);
         }
+        Item::Stimulus(d) => {
+            w.kv_str("kind", "stimulus");
+            w.comma_nl();
+            w.kv_str("layer", &d.layer.name);
+            w.comma_nl();
+            w.key("model");
+            emit_stimulus_model(w, &d.model);
+        }
         Item::Run(d) => {
             w.kv_str("kind", "run");
             w.comma_nl();
             w.key("duration");
             emit_quantity(w, &d.duration);
+            w.comma_nl();
+            w.key("step");
+            if let Some(step) = &d.step {
+                emit_quantity(w, step);
+            } else {
+                emit_quantity_value(w, 1.0, Some("ms"));
+            }
+            w.comma_nl();
+            w.kv_u64("seed", seed);
+        }
+        Item::Seed(_) => {}
+    }
+    w.obj_end();
+}
+
+fn emit_stimulus_model(w: &mut JsonWriter, model: &StimulusModel) {
+    w.obj_begin();
+    match model {
+        StimulusModel::Poisson { rate } => {
+            w.kv_str("type", "poisson");
+            w.comma_nl();
+            w.key("rate");
+            emit_quantity(w, rate);
         }
     }
     w.obj_end();
@@ -126,11 +173,15 @@ fn emit_expr(w: &mut JsonWriter, e: &Expr) {
 }
 
 fn emit_quantity(w: &mut JsonWriter, q: &Quantity) {
+    emit_quantity_value(w, q.value, q.unit.as_ref().map(|u| u.name.as_str()));
+}
+
+fn emit_quantity_value(w: &mut JsonWriter, value: f64, unit: Option<&str>) {
     w.obj_begin();
-    w.kv_f64("value", q.value);
-    if let Some(u) = &q.unit {
+    w.kv_f64("value", value);
+    if let Some(u) = unit {
         w.comma_nl();
-        w.kv_str("unit", &u.name);
+        w.kv_str("unit", u);
     }
     w.obj_end();
 }

crates/converge-lang/src/emit.rs

@@ -11,6 +11,10 @@ pub enum TokenKind {
     KwConnect,
     KwRun,
     KwFor,
+    KwSeed,
+    KwStep,
+    KwStimulus,
+    KwRate,
 
     LBrace,
     RBrace,
@@ -206,6 +210,10 @@ impl<'a> Lexer<'a> {
             "connect" => TokenKind::KwConnect,
             "run" => TokenKind::KwRun,
             "for" => TokenKind::KwFor,
+            "seed" => TokenKind::KwSeed,
+            "step" => TokenKind::KwStep,
+            "stimulus" => TokenKind::KwStimulus,
+            "rate" => TokenKind::KwRate,
             _ => TokenKind::Ident(text.to_string()),
         };
         Ok(Token {

crates/converge-lang/src/lexer.rs

@@ -5,4 +5,5 @@ pub mod diagnostic;
 pub mod emit;
 pub mod lexer;
 pub mod parser;
+pub mod units;
 pub mod validate;