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)/artifacts/omega/souc-bin/souc-linux-x86_64-jit"
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

Canonical GPU-profile examples

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.