Compiler API Reference¶

Network-to-hardware compilation pipeline. Arbitrary ODE strings to synthesizable Verilog RTL in one function call.

CLI¶

sc-neurocore compile "dv/dt = -(v-E_L)/tau_m + I/C" \
    --threshold "v > -50" --reset "v = -65" \
    --params "E_L=-65,tau_m=10,C=1" --init "v=-65" \
    --target ice40 --testbench --synthesize -o build/

Flag	Default	Description
`--threshold`	None	Spike condition (e.g. `"v > -50"`)
`--reset`	None	Reset expression (e.g. `"v = -65; w = 0"`)
`--params`	None	Comma-separated `key=val` pairs
`--init`	None	Initial state `key=val` pairs
`--target`	`ice40`	FPGA target (`ice40`, `ecp5`, `artix7`, `zynq`)
`--module-name`	`sc_equation_neuron`	Generated Verilog module name
`--testbench`	off	Generate simulation testbench
`--synthesize`	off	Run Yosys synthesis (requires Yosys in PATH)
`-o` / `--output`	`build`	Output directory

Equation → Verilog Compiler¶

Compile arbitrary ODE neuron equations to synthesizable Verilog RTL.

Supported functions¶

Category	Functions
Transcendental	`exp`, `log`, `sqrt`, `tanh`, `sigmoid`, `sin`, `cos`
Arithmetic	`abs`, `clip(x, lo, hi)`, `max(a, b)`, `min(a, b)`
Polynomial	`x2` through `x8`
Operators	`+`, `-`, `*`, `/` (by constant), unary `-`
Comparison	`>`, `>=`, `<`, `<=`

Transcendental functions use 16-entry piecewise Q8.8 lookup tables covering [-8, +8). Accuracy: ~1-2% over the useful range for neuron dynamics. All arithmetic includes saturating overflow protection.

flowchart TB
    subgraph Input
        A["ODE string<br/>'dv/dt = -(v-E_L)/tau + I/C'"]
    end
    subgraph Parse
        B["Python AST parser"]
        C["_VerilogExprEmitter"]
    end
    subgraph Emit
        D["Q8.8 parameters"]
        E["Multiply pipelines"]
        F["LUT for exp/log/tanh"]
        G["Saturating next-state"]
        H["Threshold + reset logic"]
    end
    subgraph Output
        I["Synthesizable Verilog"]
        J["Testbench"]
    end

    A --> B --> C
    C --> D & E & F & G & H
    D & E & F & G & H --> I
    I --> J

    style Input fill:#e1f5fe
    style Output fill:#e8f5e9

`sc_neurocore.compiler.equation_compiler` ¶

Compile arbitrary ODE neuron equations to synthesizable Verilog.

Compile string equations directly to FPGA hardware:

from sc_neurocore.neurons.equation_builder import from_equations
from sc_neurocore.compiler.equation_compiler import compile_to_verilog

neuron = from_equations("dv/dt = -(v - E_L)/tau_m + I/C",
                        threshold="v > -50", reset="v = -65",
                        params=dict(E_L=-65, tau_m=10, C=1),
                        init=dict(v=-65))

verilog = compile_to_verilog(neuron, module_name="my_lif")

All arithmetic uses Q8.8 signed fixed-point. Each ODE term becomes a multiply-shift pipeline stage. Threshold and reset map to combinational comparators and mux logic.

`Q88` `dataclass` ¶

Q8.8 fixed-point conversion: 8 integer bits, 8 fractional bits, signed.

Source code in src/sc_neurocore/compiler/equation_compiler.py

@dataclass
class Q88:
    """Q8.8 fixed-point conversion: 8 integer bits, 8 fractional bits, signed."""

    data_width: int = 16
    fraction: int = 8

    def encode(self, value: float) -> int:
        raw = int(round(value * (1 << self.fraction)))
        mask = (1 << self.data_width) - 1
        return raw & mask

    def encode_signed_literal(self, value: float) -> str:
        raw = int(round(value * (1 << self.fraction)))
        if raw < 0:
            raw = raw & ((1 << self.data_width) - 1)
        return f"{self.data_width}'sd{raw}"

`compile_to_verilog(neuron, module_name='sc_equation_neuron', data_width=16, fraction=8)` ¶

Compile an EquationNeuron to synthesizable Verilog RTL.

Parameters¶

neuron : EquationNeuron The neuron defined by arbitrary ODE strings. module_name : str Name of the generated Verilog module. data_width : int Bit width for fixed-point arithmetic (default 16 = Q8.8). fraction : int Number of fractional bits (default 8).

Returns¶

str Synthesizable Verilog source code.

Source code in src/sc_neurocore/compiler/equation_compiler.py

def compile_to_verilog(
    neuron: EquationNeuron,
    module_name: str = "sc_equation_neuron",
    data_width: int = 16,
    fraction: int = 8,
) -> str:
    """Compile an EquationNeuron to synthesizable Verilog RTL.

    Parameters
    ----------
    neuron : EquationNeuron
        The neuron defined by arbitrary ODE strings.
    module_name : str
        Name of the generated Verilog module.
    data_width : int
        Bit width for fixed-point arithmetic (default 16 = Q8.8).
    fraction : int
        Number of fractional bits (default 8).

    Returns
    -------
    str
        Synthesizable Verilog source code.
    """
    q = Q88(data_width=data_width, fraction=fraction)
    state_vars = set(neuron.equations.keys())

    # Build parameter map: Python name → Verilog parameter name
    param_map: dict[str, str] = {}
    param_decls: list[str] = []
    for pname, pval in {**neuron.parameters, **neuron.constants}.items():
        vname = f"P_{pname.upper()}"
        param_map[pname] = vname
        q_val = q.encode(pval)
        param_decls.append(
            f"    parameter signed [{data_width - 1}:0] {vname} = {data_width}'sd{q_val}"
        )

    # Generate derivative expressions
    deriv_wires: list[str] = []
    deriv_assigns: list[str] = []
    all_intermediates: list[str] = []

    for var, expr_str in neuron.equations.items():
        vexpr, intermediates = _emit_expr(expr_str, state_vars, param_map, q)
        all_intermediates.extend(intermediates)
        # dv = expr * dt (multiply by dt in fixed-point)
        dt_literal = q.encode_signed_literal(neuron.dt)
        dt_tmp = f"_dt_mul_{var}"
        all_intermediates.append(
            f"wire signed [{2 * data_width - 1}:0] {dt_tmp} = ({vexpr}) * {dt_literal};"
        )
        deriv_name = f"d{var}"
        deriv_wires.append(
            f"wire signed [{data_width - 1}:0] {deriv_name} = ({dt_tmp} >>> {fraction})[{data_width - 1}:0];"
        )

    # Next-state computation with saturation
    max_val = (1 << (data_width - 1)) - 1  # e.g. 32767 for 16-bit
    min_val = -(1 << (data_width - 1))  # e.g. -32768 for 16-bit
    next_wires: list[str] = []
    for var in neuron.equations:
        raw = f"{var}_raw"
        next_wires.append(f"wire signed [{data_width}:0] {raw} = {var}_reg + d{var};")
        next_wires.append(
            f"wire signed [{data_width - 1}:0] {var}_next = "
            f"({raw} > {data_width + 1}'sd{max_val}) ? {data_width}'sd{max_val} : "
            f"({raw} < {data_width + 1}'sd{min_val}) ? {data_width}'sd{min_val} : "
            f"{raw}[{data_width - 1}:0];"
        )

    # Threshold expression
    threshold_verilog = ""
    if neuron.threshold_expr:
        threshold_verilog, thr_intermediates = _emit_expr(
            neuron.threshold_expr, state_vars, param_map, q
        )
        all_intermediates.extend(thr_intermediates)

    # Reset assignments
    reset_assignments: list[str] = []
    for var, expr_str in neuron.reset_rules.items():
        rexpr, r_intermediates = _emit_expr(expr_str, state_vars, param_map, q)
        all_intermediates.extend(r_intermediates)
        reset_assignments.append(f"                    {var}_reg <= {rexpr};")

    # Build the Verilog module
    lines = [
        "// Auto-generated by SC-NeuroCore equation compiler",
        f"// Source: {neuron!r}",
        f"// Fixed-point: Q{data_width - fraction}.{fraction} ({data_width}-bit signed)",
        "`timescale 1ns / 1ps",
        "",
        f"module {module_name} #(",
    ]
    lines.append(",\n".join(param_decls))
    lines.append(")(")
    lines.append("    input wire clk,")
    lines.append("    input wire rst_n,")
    lines.append(f"    input wire signed [{data_width - 1}:0] I_t,")
    lines.append("    output reg spike_out,")

    # Output ports for each state variable
    for var in neuron.equations:
        lines.append(f"    output reg signed [{data_width - 1}:0] {var}_out,")
    # Remove trailing comma from last port
    lines[-1] = lines[-1].rstrip(",")
    lines.append(");")
    lines.append("")

    # State registers
    for var in neuron.equations:
        init_val = q.encode_signed_literal(neuron.initial_state.get(var, 0.0))
        lines.append(f"reg signed [{data_width - 1}:0] {var}_reg;")

    lines.append("")

    # Intermediate wires (multiply pipelines)
    for wire in all_intermediates:
        lines.append(wire)
    lines.append("")

    # Derivative wires
    for wire in deriv_wires:
        lines.append(wire)
    lines.append("")

    # Next-state wires
    for wire in next_wires:
        lines.append(wire)
    lines.append("")

    # Sequential logic
    lines.append("always @(posedge clk or negedge rst_n) begin")
    lines.append("    if (!rst_n) begin")
    for var in neuron.equations:
        init_val = q.encode_signed_literal(neuron.initial_state.get(var, 0.0))
        lines.append(f"        {var}_reg <= {init_val};")
        lines.append(f"        {var}_out <= {init_val};")
    lines.append("        spike_out <= 1'b0;")
    lines.append("    end else begin")

    if threshold_verilog:
        lines.append(f"        if ({threshold_verilog}) begin")
        lines.append("            spike_out <= 1'b1;")
        for assign in reset_assignments:
            lines.append(assign)
        # State vars not in reset keep their next value
        for var in neuron.equations:
            if var not in neuron.reset_rules:
                lines.append(f"            {var}_reg <= {var}_next;")
        for var in neuron.equations:
            reset_val = (
                f"{param_map.get(var + '_reset_val', var + '_next')}"
                if var in neuron.reset_rules
                else f"{var}_next"
            )
            lines.append(f"            {var}_out <= {var}_reg;")
        lines.append("        end else begin")
        lines.append("            spike_out <= 1'b0;")
        for var in neuron.equations:
            lines.append(f"            {var}_reg <= {var}_next;")
            lines.append(f"            {var}_out <= {var}_next;")
        lines.append("        end")
    else:
        lines.append("        spike_out <= 1'b0;")
        for var in neuron.equations:
            lines.append(f"        {var}_reg <= {var}_next;")
            lines.append(f"        {var}_out <= {var}_next;")

    lines.append("    end")
    lines.append("end")
    lines.append("")
    lines.append("endmodule")

    return "\n".join(lines)

`equation_to_fpga(*equation_strings, threshold=None, reset=None, params=None, init=None, dt=0.1, module_name='sc_equation_neuron')` ¶

One-liner: ODE string → (Python neuron, Verilog RTL).

neuron, verilog = equation_to_fpga( ... "dv/dt = -(v - E_L)/tau_m + I/C", ... threshold="v > -50", reset="v = -65", ... params=dict(E_L=-65, tau_m=10, C=1), ... init=dict(v=-65), ... )

Source code in src/sc_neurocore/compiler/equation_compiler.py

def equation_to_fpga(
    *equation_strings: str,
    threshold: str | None = None,
    reset: str | None = None,
    params: dict[str, float] | None = None,
    init: dict[str, float] | None = None,
    dt: float = 0.1,
    module_name: str = "sc_equation_neuron",
) -> tuple[EquationNeuron, str]:
    """One-liner: ODE string → (Python neuron, Verilog RTL).

    >>> neuron, verilog = equation_to_fpga(
    ...     "dv/dt = -(v - E_L)/tau_m + I/C",
    ...     threshold="v > -50", reset="v = -65",
    ...     params=dict(E_L=-65, tau_m=10, C=1),
    ...     init=dict(v=-65),
    ... )
    """
    from ..neurons.equation_builder import from_equations

    # Split semicolons within single strings for convenience
    expanded = []
    for s in equation_strings:
        expanded.extend(part.strip() for part in s.split(";") if part.strip())

    neuron = from_equations(
        *expanded,
        threshold=threshold,
        reset=reset,
        params=params,
        init=init,
        dt=dt,
    )
    verilog = compile_to_verilog(neuron, module_name=module_name)
    return neuron, verilog

`generate_testbench(neuron, module_name='sc_equation_neuron', n_steps=200, input_current=1.0, data_width=16, fraction=8)` ¶

Generate a Verilog testbench for a compiled equation neuron.

Drives the module with constant current for n_steps clock cycles, monitors spike_out and state outputs, and produces a VCD waveform.

Parameters¶

neuron : EquationNeuron The neuron (same one passed to compile_to_verilog). module_name : str Must match the module name used in compile_to_verilog. n_steps : int Number of simulation clock cycles. input_current : float Constant input current (Q-encoded internally). data_width : int Bit width matching the compiled module. fraction : int Fractional bits matching the compiled module.

Returns¶

str Verilog testbench source code.

Source code in src/sc_neurocore/compiler/equation_compiler.py

def generate_testbench(
    neuron: EquationNeuron,
    module_name: str = "sc_equation_neuron",
    n_steps: int = 200,
    input_current: float = 1.0,
    data_width: int = 16,
    fraction: int = 8,
) -> str:
    """Generate a Verilog testbench for a compiled equation neuron.

    Drives the module with constant current for n_steps clock cycles,
    monitors spike_out and state outputs, and produces a VCD waveform.

    Parameters
    ----------
    neuron : EquationNeuron
        The neuron (same one passed to compile_to_verilog).
    module_name : str
        Must match the module name used in compile_to_verilog.
    n_steps : int
        Number of simulation clock cycles.
    input_current : float
        Constant input current (Q-encoded internally).
    data_width : int
        Bit width matching the compiled module.
    fraction : int
        Fractional bits matching the compiled module.

    Returns
    -------
    str
        Verilog testbench source code.
    """
    q = Q88(data_width=data_width, fraction=fraction)
    i_val = q.encode_signed_literal(input_current)

    state_vars = list(neuron.equations.keys())
    port_connections = [
        "    .clk(clk),",
        "    .rst_n(rst_n),",
        f"    .I_t({i_val}),",
        "    .spike_out(spike_out),",
    ]
    wire_decls = []
    for var in state_vars:
        port_connections.append(f"    .{var}_out({var}_out),")
        wire_decls.append(f"wire signed [{data_width - 1}:0] {var}_out;")
    port_connections[-1] = port_connections[-1].rstrip(",")

    lines = [
        f"// Auto-generated testbench for {module_name}",
        "// SC-NeuroCore equation compiler",
        "`timescale 1ns / 1ps",
        "",
        f"module tb_{module_name};",
        "",
        "reg clk;",
        "reg rst_n;",
        "wire spike_out;",
    ]
    lines.extend(wire_decls)
    lines.append("")
    lines.append(f"{module_name} uut (")
    lines.extend(port_connections)
    lines.append(");")
    lines.append("")
    lines.append("// Clock: 10ns period (100 MHz)")
    lines.append("initial clk = 0;")
    lines.append("always #5 clk = ~clk;")
    lines.append("")
    lines.append("integer spike_count;")
    lines.append("")
    lines.append("initial begin")
    lines.append(f'    $dumpfile("tb_{module_name}.vcd");')
    lines.append(f"    $dumpvars(0, tb_{module_name});")
    lines.append("    spike_count = 0;")
    lines.append("")
    lines.append("    // Reset")
    lines.append("    rst_n = 0;")
    lines.append("    #20;")
    lines.append("    rst_n = 1;")
    lines.append("")
    lines.append(f"    // Run {n_steps} cycles")
    lines.append(f"    repeat ({n_steps}) begin")
    lines.append("        @(posedge clk);")
    lines.append("        if (spike_out) spike_count = spike_count + 1;")
    lines.append("    end")
    lines.append("")
    lines.append(
        f'    $display("Simulation complete: %0d spikes in {n_steps} cycles", spike_count);'
    )
    for var in state_vars:
        lines.append(
            f'    $display("Final {var} = %0d (Q{data_width - fraction}.{fraction})", {var}_out);'
        )
    lines.append("    $finish;")
    lines.append("end")
    lines.append("")
    lines.append("endmodule")

    return "\n".join(lines)

Pipeline¶

Orchestration pipeline: MLIR → firtool → Verilog → Yosys → nextpnr → bitstream.

`sc_neurocore.compiler.pipeline` ¶

Orchestration Pipeline for sc-neurocore's Hardware Compiler.

This module provides the automated workflow to take a stochastic graph from the MLIREmitter and compile it down to a bitstream using open-source FPGA tools: 1. CIRCT (firtool) -> Verilog 2. Yosys -> Synthesis (BLIF/JSON) 3. NextPNR -> Place & Route 4. IcePack / Project Xray -> Bitstream

`CompilerPipeline` ¶

Automated hardware synthesis pipeline.

Source code in src/sc_neurocore/compiler/pipeline.py

class CompilerPipeline:
    """
    Automated hardware synthesis pipeline.
    """

    def __init__(self, work_dir: str = ".tmp/compiler"):
        self.work_dir = os.path.realpath(work_dir)
        if not os.path.exists(self.work_dir):
            os.makedirs(self.work_dir)

    @staticmethod
    def _sanitize_name(name: str) -> str:
        """Restrict output_name to alphanumeric + underscore."""
        sanitized = "".join(c for c in name if c.isalnum() or c == "_")
        if not sanitized:
            from sc_neurocore.exceptions import SCCompilerError

            raise SCCompilerError(f"Invalid output name: {name!r}")
        return sanitized

    def compile_mlir_to_verilog(self, mlir_content: str, output_name: str = "top") -> str:
        """
        Invokes 'firtool' to lower MLIR to Verilog.
        """
        output_name = self._sanitize_name(output_name)
        mlir_path = os.path.join(self.work_dir, f"{output_name}.mlir")
        v_path = os.path.join(self.work_dir, f"{output_name}.v")

        with open(mlir_path, "w") as f:
            f.write(mlir_content)

        logger.info(f"Lowering {mlir_path} to Verilog...")
        # Note: In a real environment, firtool must be in PATH
        try:
            subprocess.run(["firtool", mlir_path, "-o", v_path], check=True)
        except (subprocess.CalledProcessError, FileNotFoundError) as e:
            logger.warning(f"firtool failed or not found: {e}. Falling back to stub Verilog.")
            # Fallback for demo/development without full toolchain
            with open(v_path, "w") as f:
                f.write(
                    f"// Stub Verilog generated for {output_name}\nmodule {output_name}(); endmodule"
                )

        return v_path

    _ALLOWED_TARGETS = {"ice40", "ecp5", "gowin", "xilinx"}

    def _validate_path(self, path: str) -> str:
        """Ensure path resolves inside work_dir."""
        real = os.path.realpath(path)
        if not real.startswith(self.work_dir):
            from sc_neurocore.exceptions import SCCompilerError

            raise SCCompilerError(f"Path escapes work_dir: {path!r}")
        return real

    def run_synthesis(self, v_path: str, target_fpga: str = "ice40") -> str:
        """
        Invokes 'yosys' for synthesis.
        """
        v_path = self._validate_path(v_path)
        if target_fpga not in self._ALLOWED_TARGETS:
            from sc_neurocore.exceptions import SCCompilerError

            raise SCCompilerError(f"Unknown target FPGA: {target_fpga!r}")

        base = os.path.splitext(v_path)[0]
        json_path = f"{base}.json"

        logger.info(f"Synthesizing {v_path} for {target_fpga}...")
        # Use yosys script file to avoid shell metacharacter injection via -p
        script = f"read_verilog {v_path}; synth_{target_fpga} -json {json_path}"
        script_path = f"{base}_synth.ys"
        with open(script_path, "w") as f:
            f.write(script)

        try:
            subprocess.run(["yosys", "-s", script_path], check=True)
        except (subprocess.CalledProcessError, FileNotFoundError) as e:
            logger.warning(f"yosys failed or not found: {e}")

        return json_path

    def run_pnr(self, json_path: str, target_device: str = "up5k") -> str:
        """
        Invokes 'nextpnr' for place and route.
        """
        json_path = self._validate_path(json_path)
        asc_path = f"{os.path.splitext(json_path)[0]}.asc"

        logger.info(f"Running P&R for {target_device}...")
        pnr_cmd = ["nextpnr-ice40", "--up5k", "--json", json_path, "--asc", asc_path]

        try:
            subprocess.run(pnr_cmd, check=True)
        except (subprocess.CalledProcessError, FileNotFoundError) as e:
            logger.warning(f"nextpnr failed or not found: {e}")

        return asc_path

`compile_mlir_to_verilog(mlir_content, output_name='top')` ¶

Invokes 'firtool' to lower MLIR to Verilog.

Source code in src/sc_neurocore/compiler/pipeline.py

def compile_mlir_to_verilog(self, mlir_content: str, output_name: str = "top") -> str:
    """
    Invokes 'firtool' to lower MLIR to Verilog.
    """
    output_name = self._sanitize_name(output_name)
    mlir_path = os.path.join(self.work_dir, f"{output_name}.mlir")
    v_path = os.path.join(self.work_dir, f"{output_name}.v")

    with open(mlir_path, "w") as f:
        f.write(mlir_content)

    logger.info(f"Lowering {mlir_path} to Verilog...")
    # Note: In a real environment, firtool must be in PATH
    try:
        subprocess.run(["firtool", mlir_path, "-o", v_path], check=True)
    except (subprocess.CalledProcessError, FileNotFoundError) as e:
        logger.warning(f"firtool failed or not found: {e}. Falling back to stub Verilog.")
        # Fallback for demo/development without full toolchain
        with open(v_path, "w") as f:
            f.write(
                f"// Stub Verilog generated for {output_name}\nmodule {output_name}(); endmodule"
            )

    return v_path

`run_synthesis(v_path, target_fpga='ice40')` ¶

Invokes 'yosys' for synthesis.

Source code in src/sc_neurocore/compiler/pipeline.py

def run_synthesis(self, v_path: str, target_fpga: str = "ice40") -> str:
    """
    Invokes 'yosys' for synthesis.
    """
    v_path = self._validate_path(v_path)
    if target_fpga not in self._ALLOWED_TARGETS:
        from sc_neurocore.exceptions import SCCompilerError

        raise SCCompilerError(f"Unknown target FPGA: {target_fpga!r}")

    base = os.path.splitext(v_path)[0]
    json_path = f"{base}.json"

    logger.info(f"Synthesizing {v_path} for {target_fpga}...")
    # Use yosys script file to avoid shell metacharacter injection via -p
    script = f"read_verilog {v_path}; synth_{target_fpga} -json {json_path}"
    script_path = f"{base}_synth.ys"
    with open(script_path, "w") as f:
        f.write(script)

    try:
        subprocess.run(["yosys", "-s", script_path], check=True)
    except (subprocess.CalledProcessError, FileNotFoundError) as e:
        logger.warning(f"yosys failed or not found: {e}")

    return json_path

`run_pnr(json_path, target_device='up5k')` ¶

Invokes 'nextpnr' for place and route.

Source code in src/sc_neurocore/compiler/pipeline.py

def run_pnr(self, json_path: str, target_device: str = "up5k") -> str:
    """
    Invokes 'nextpnr' for place and route.
    """
    json_path = self._validate_path(json_path)
    asc_path = f"{os.path.splitext(json_path)[0]}.asc"

    logger.info(f"Running P&R for {target_device}...")
    pnr_cmd = ["nextpnr-ice40", "--up5k", "--json", json_path, "--asc", asc_path]

    try:
        subprocess.run(pnr_cmd, check=True)
    except (subprocess.CalledProcessError, FileNotFoundError) as e:
        logger.warning(f"nextpnr failed or not found: {e}")

    return asc_path

MLIR Emitter¶

`sc_neurocore.compiler.mlir_emitter` ¶

MLIR / CIRCT Emitter for Stochastic Computing pipelines.

This module provides the frontend to lower sc-neurocore's Python-based Stochastic IR into MLIR hardware dialects (HW, Seq, Comb) via CIRCT. This allows us to leverage LLVM's optimization passes directly for FPGA bitstream synthesis, skipping string-based Verilog generation.