Examples

Where to find runnable Sounio code in the repo.

Examples

Examples are only useful when readers know which ones to trust. In Sounio, that means separating onboarding material, proof-bearing tests, domain fixtures, and exploratory directories instead of treating everything under examples/ as equally authoritative.

Trust order

  • tests/run-pass/ and tests/compile-fail/ are the strongest source of language-level behavior.
  • tests/stdlib/ and the corresponding artifacts are the strongest source of stdlib and science-lane claims.
  • examples/ is valuable for onboarding and browsing ideas, but some paths there are exploratory or backend-dependent.
  • self-hosted/ is where compiler implementation examples and verification surfaces live, not end-user programs.

Canonical public examples

export SOUC_BIN="$(pwd)/bin/souc"
export SOUNIO_STDLIB_PATH="$(pwd)/stdlib"

"$SOUC_BIN" check examples/hello.sio
"$SOUC_BIN" check tests/run-pass/covid_2020_kernel.sio
"$SOUC_BIN" check tests/run-pass/vancomycin_propagation.sio
"$SOUC_BIN" check tests/compile-fail/vancomycin_low_conf.sio

Self-hosted GPU artifact-template examples

The default self-hosted compiler compiles GPU syntax and lets kretikos emit predefined artifact templates:

# Check GPU kernel syntax on the self-hosted compiler
bin/souc check examples/kernel_source_level.sio

# Emit predefined PTX templates (self-hosted, no GPU required)
kretikos emit-ptx vec_add     -o /tmp/kernel.ptx
kretikos emit-ptx vec_sub     -o /tmp/kernel.ptx
kretikos emit-ptx vec_mul     -o /tmp/kernel.ptx
kretikos emit-ptx vec_div     -o /tmp/kernel.ptx
kretikos emit-ptx vec_add_f64 -o /tmp/kernel.ptx
kretikos emit-ptx fma         -o /tmp/kernel.ptx
kretikos emit-ptx fma_f64     -o /tmp/kernel.ptx
kretikos emit-ptx store_u32_const -o /tmp/kernel.ptx

# Emit predefined Metal/MSL templates (self-hosted, no macOS required)
kretikos emit-metal vec_add          -o /tmp/kernel.metal
kretikos emit-metal ossm_oct_step    -o /tmp/kernel.metal
kretikos emit-metal sedenion_cd_step -o /tmp/kernel.metal

# Emit the predefined vec_add_f32 CUBIN template
kretikos emit-cubin vec_add_f32 -o /tmp/kernel.cubin

# Emit PTX+CUBIN plus a structural bundle manifest
kretikos bundle -o /tmp/kretikos-bundle

# On a CUDA host, add optional toolchain/runtime validation to the manifest
kretikos bundle -o /tmp/kretikos-validated-bundle --validate-toolchain --validate-runtime

GPU artifact examples (broader pattern support)

The separate GPU artifact supports more kernel patterns:

export SOUC_GPU_BIN="$(pwd)/artifacts/omega/souc-bin/souc-linux-x86_64-gpu"
export SOUNIO_STDLIB_PATH="$(pwd)/stdlib"

"$SOUC_GPU_BIN" check examples/gpu.sio
"$SOUC_GPU_BIN" check examples/kernel_vec_add.sio
"$SOUC_GPU_BIN" check tests/run-pass/gpu_launch_surface.sio
"$SOUC_GPU_BIN" build examples/kernel_matmul.sio --backend gpu -o /tmp/kernel_matmul.ptx

High-value directories

  • examples/io/, examples/effects/, and examples/epistemic/ are good places for small teaching programs.
  • examples/gpu.sio, examples/kernel_vec_add.sio, and examples/kernel_matmul.sio are the current public GPU-profile examples.
  • tests/run-pass/ and tests/compile-fail/ are where you should look when documenting accepted and rejected language behavior.
  • tests/stdlib/ is where domain lanes such as fmri, darwin_pbpk, nn, onn, qnn, snn, spnn, quantnn, and math prove themselves.
  • docs/research/vancomycin-uncertainty.md ties one of the most important public examples back to a longer narrative.

Documentation guidance

  • When showing an example, say whether it was merely read from the tree, checked with souc check, or executed end-to-end.
  • Prefer examples that align with current gate artifacts when making strong claims.
  • If an example relies on GPU, LLVM, LSP, or another gated backend, state that dependency plainly.