SonicBoom

Blade (formerly S-Expr) — user-facing format; lowers to Boom IR.

SonicBoom Blade v0.2 — Draft

Status: DRAFT, not frozen. Derived from the graphs the Guile tracing prototype (bindings/guile/scheme/sonicboom/trace/) actually emits. Base: s-expr-v0-spec.md (Blade v0.1, FROZEN). Everything in v0.1 stays valid; this draft lists only the increments. Checked by: (sonicboom trace validate) (§11).

0. Summary of increments

# Increment Kind Core / optional
1 Multi-output graphs: ordered outputs, pass-through outputs semantics on v0.1 syntax core
2 Tensor-list inputs: flat inputs named <base>.<k>, bound by name naming convention + semantics core (convention), optional (structure metadata)
3 aten node attribute: Core ATen dispatch key attribute convention + validity rule core to accept and check; dispatch by it is optional
4 Constant parameters: rank-0, integer and bool constants, value-count rule tightened v0.1 rule core
5 loop node: host loop over a nested body graph new op with a nested document optional
6 Side-effect nodes (print) and their ordering semantics new op class optional
7 dtype and shape rules: a typing rule per op, checked against declarations new validity rule core
8 Attribute type representation: per-attribute tags, booleans, empty lists, document strings conventions on v0.1 attribute syntax core
9 Op vocabulary with arities new normative table core, except loop and print
10 Version (version 0 2) header core

The rules for optional features:

The prototype still writes (version 0 1) on every document, including ones that use v0.2 increments; its output format is not changed by this draft. The validator accepts both versions with the v0.2 rules. Once the draft is adopted, a writer MUST declare (version 0 2) whenever it uses any increment marked “new” above (items 3 and 5–7 and the vocabulary of 9).


1. Multi-output graphs (core)

Syntax. Unchanged from v0.1:

(outputs (output <string>)*)

Semantics (new).

Minimal example (two results, the second passed through):

(sonicboom-s-expr
  (version 0 2)
  (graph
    (name "two-outputs")
    (inputs
      (input "arg0.0" (tensor float32 (shape 2)))
      (input "arg1" (tensor float32 (shape 2)))
      (input "arg0.1" (tensor float32 (shape 2))))
    (outputs
      (output "v0")
      (output "arg0.1"))
    (parameters)
    (nodes
      (node add (inputs "arg0.0" "arg1") (outputs ("v0" (tensor float32 (shape 2))))
            (attrs (aten (string "aten::add.Tensor")))))))

2. Tensor-list inputs (core convention)

Syntax. Unchanged: flat (input <string> <type>) entries.

Naming convention (new).

Semantics (new).

Optional, not emitted yet. An explicit (input-group <string> <string>*) section naming the members of each list, for readers that want the structure without parsing names. It is reserved and not used by the prototype.

Minimal example: the graph in §1. arg0 was a two-element list.

3. The aten attribute (core to accept and check; dispatch optional)

Syntax. An ordinary v0.1 attribute:

(aten (string "<namespace>::<op>[.<overload>]"))

Semantics (new).

Whether native-torch actually has a kernel for each name is recorded in the Guile tracing prototype notes.

Minimal example:

(node mul (inputs "arg0" "c0") (outputs ("v1" (tensor float32 (shape 2))))
      (attrs (aten (string "aten::mul.Tensor"))))

4. Constant parameters (core)

Syntax. Unchanged v0.1 parameter with (data :values <atom>*).

Tightened rules (new).

Minimal example:

(parameters
  (parameter "c0" (tensor int64 (shape 2)) (data :values 1 0))
  (parameter "c2" (tensor bool (shape 2 2)) (data :values #t #f #t #t))
  (parameter "c3" (tensor float32 (shape)) (data :values 0.0)))

5. loop node: host loop (optional)

Syntax:

(node loop
  (inputs <state>… <invariant>…)
  (outputs (<name> <type>)…)              ; one per state input
  (attrs (body (string "<document>"))     ; a complete Blade document
         (trip_count (int <n>))           ; n >= 0
         (state_count (int <k>))))        ; 0 <= k <= number of inputs

Semantics.

Minimal example (halve a vector three times; this is the prototype’s output, with the body text written by write):

(sonicboom-s-expr
  (version 0 2)
  (graph
    (name "halve3")
    (inputs
      (input "arg0" (tensor float32 (shape 2))))
    (outputs
      (output "v14"))
    (parameters)
    (nodes
      (node loop (inputs "arg0") (outputs ("v14" (tensor float32 (shape 2))))
            (attrs (body (string "(sonicboom-s-expr (version 0 2) (graph (name \"loop-body\") (inputs (input \"s0\" (tensor float32 (shape 2)))) (outputs (output \"t1\")) (parameters (parameter \"p0\" (tensor float32 (shape)) (data :values 0.5))) (nodes (node mul (inputs \"s0\" \"p0\") (outputs (\"t1\" (tensor float32 (shape 2)))) (attrs (aten (string \"aten::mul.Tensor\")))))))"))
                   (trip_count (int 3))
                   (state_count (int 1)))))))

6. Side-effect nodes: print (optional)

Syntax:

(node print (inputs <x>) (outputs (<y> <type-of-x>)) (attrs (label (string "<label>"))))

Semantics.

Minimal example:

(nodes
  (node mul (inputs "arg0" "c0") (outputs ("v1" (tensor float32 (shape 2))))
        (attrs (aten (string "aten::mul.Tensor"))))
  (node print (inputs "v1") (outputs ("v2" (tensor float32 (shape 2))))
        (attrs (label (string "dbl"))))
  (node add (inputs "arg0" "c3") (outputs ("v4" (tensor float32 (shape 2))))
        (attrs (aten (string "aten::add.Tensor")))))

7. dtype and shape rules (core)

v0.1 requires every value to be typed but leaves the meaning of ops to the registry. v0.2 makes the typing rules normative for the vocabulary of §9. A document is valid only if every node’s declared output type equals the type its rule derives from the input types and attributes.

Ops dtype rule Shape rule
add sub mul div inputs equal, numeric; output the same NumPy broadcasting of the inputs
greater less inputs equal, numeric; output bool broadcasting
equal inputs equal; output bool broadcasting
and or / not inputs bool; output bool broadcasting / unchanged
neg relu numeric; unchanged unchanged
exp log tanh sqrt gelu float; unchanged unchanged
where condition bool; branches equal; output = branch dtype broadcast of all three
matmul equal [m k] × [k n] → [m n]
bmm equal [b m k] × [b k n] → [b m n]
permute unchanged out[i] = in[dims[i]]; dims a permutation
reshape unchanged shape attr, same element count
expand unchanged shape attr, which the input must broadcast to
reduce_sum reduce_mean reduce_max unchanged drop the axes (all axes if empty); keep them as 1 if keepdims = 1
index_select x any, index 1-D integer x with axis replaced by len(index)
index_add base, source, index 1-D integer output = base; source has the index_select shape
gather index integer, same rank as x index’s shape
scatter_add index and source same shape output = base
concat all equal equal off axis; sizes summed on axis
slice unchanged axis extent end − start, 0 ≤ start ≤ end ≤ extent
print unchanged unchanged
loop §5 §5

Constants obey the same rules as any value. A Scheme literal combined with an int64 tensor becomes an int64 constant.

8. Attribute type representation (core)

v0.1 syntax: (<name> (<tag> <value>…)), with tags int float string bool ints floats strings bools. v0.2 fixes the tag of each attribute the vocabulary uses:

Attribute Tag Used by Notes
axes ints reduce_* may be empty: (axes (ints)) means all axes; negative values count from the end
keepdims int reduce_* 0 or 1. Booleans of the vocabulary are written as int 0/1, as in ONNX
shape ints reshape, expand
dims ints permute a permutation of 0 … rank−1
axis int index_select index_add gather scatter_add concat slice
start, end int slice step is 1
label string print
aten string every mapped op (§3)
body string loop a whole document, escaped by the writer’s string syntax
trip_count, state_count int loop

Other rules:

Minimal example:

(node reduce_sum (inputs "v1") (outputs ("v2" (tensor float32 (shape 2 1))))
      (attrs (axes (ints 1)) (keepdims (int 1)) (aten (string "aten::sum.dim_IntList"))))

9. Op vocabulary (core, except loop and print)

op arity ATen (§3)
add sub mul div 2 aten::add.Tensor aten::sub.Tensor aten::mul.Tensor aten::div.Tensor
neg relu gelu 1 aten::neg aten::relu aten::gelu (tanh approximation)
exp log tanh sqrt 1 aten::exp aten::log aten::tanh aten::sqrt
matmul bmm 2 aten::mm aten::bmm
permute reshape expand 1 aten::permute aten::view aten::expand
reduce_sum reduce_mean reduce_max 1 aten::sum.dim_IntList aten::mean.dim aten::amax
greater less equal 2 aten::gt.Tensor aten::lt.Tensor aten::eq.Tensor
and or / not 2 / 1 aten::logical_and aten::logical_or / aten::logical_not
where 3 aten::where.self
index_select gather 2 aten::index_select aten::gather
index_add scatter_add 3 aten::index_add aten::scatter_add
concat ≥ 1 aten::cat
slice 1 aten::slice.Tensor
print (optional) 1 —
loop (optional) ≥ state_count —

Each op produces exactly one output, except loop, which produces state_count outputs.

The vocabulary is what the prototype emits. v0.1’s statement that op meaning belongs to a registry (§8 of v0.1) still holds. This table is the registry for the v0.2 core, and other ops remain possible in other domains.

10. Version (core)

(sonicboom-s-expr (version 0 2) (graph …))

11. Validation

(sonicboom trace validate) checks a document text against this draft:

Errors carry line L, column C from the reader and a document path such as nodes[12] (node add), or … body > nodes[0] … inside a loop body.

bindings/guile/tests/trace/test-trace-validate.scm validates:

12. Out of scope (unchanged from v0.1, or deferred)