Setup Guide

Complete guide for first-time users. No prior knowledge of Simplex required.

What You Need

Every experiment on this site is a standalone .sx file written in the Simplex programming language. To run an experiment you need three things:

1. The Simplex compiler (sxc) — compiles .sx files to LLVM IR
2. A C compiler (Clang) — links the IR with the Simplex runtime into a binary
3. The experiment source file (.sx) — downloadable from each experiment page

There are two paths: download pre-built binaries from GitHub releases (fastest) or build from source (full control).

Option A: Pre-Built Binaries (Fastest)

A1. Download

Go to github.com/senuamedia/lab/releases and download the latest release for your platform (macOS or Linux). The release contains:

• sxc — the Simplex compiler binary
• standalone_runtime.c — the C runtime (needed for linking)

A2. Install Dependencies

You need Clang (C compiler) and OpenSSL (for the runtime's crypto functions).

# macOS — Clang ships with Xcode Command Line Tools
xcode-select --install

# Install OpenSSL and Python 3 via Homebrew
brew install openssl python3

# Ubuntu / Debian Linux
sudo apt update
sudo apt install clang libssl-dev python3

A3. Verify Installation

# Check Clang is available
clang --version

# Check the Simplex compiler runs
./sxc --version
# Should print: sxc 0.17.0 (or later)

Option B: Build From Source

B1. Install Dependencies

Same as Option A — you need Clang, OpenSSL, and Python 3.

# macOS
xcode-select --install
brew install openssl python3

# Linux
sudo apt update && sudo apt install clang libssl-dev python3

B2. Clone the Repository

git clone https://github.com/senuamedia/lab.git
cd lab

B3. Build the Compiler

./build.sh

This uses the Python bootstrap compiler (stage0.py) to compile the Simplex compiler (sxc) from its own source code. The resulting binary is at build/sxc. The runtime source is at runtime/standalone_runtime.c.

B4. Verify the Build

./build/sxc --version
# Should print: sxc 0.17.0 (or later)

Running an Experiment

Every experiment page on this site includes a Download .sx button. Download the file, then follow these three steps.

Step 1: Compile the Simplex Source to LLVM IR

# Replace EXPERIMENT with the filename (e.g., exp_iratio_proof)
./sxc EXPERIMENT.sx -o EXPERIMENT.ll

This produces an LLVM IR file (.ll). The compiler will print Compilation successful. if the source is valid.

Step 2: Link with the Runtime

# macOS
OPENSSL=$(brew --prefix openssl)
clang -O2 EXPERIMENT.ll standalone_runtime.c \
  -o EXPERIMENT \
  -lm -lssl -lcrypto -L${OPENSSL}/lib

# Linux
clang -O2 EXPERIMENT.ll standalone_runtime.c \
  -o EXPERIMENT \
  -lm -lssl -lcrypto -lpthread

This produces a native executable. You need standalone_runtime.c in the same directory (or provide the full path). If you built from source, it's at simplex/runtime/standalone_runtime.c.

Step 3: Run

./EXPERIMENT

The experiment prints its results to the terminal. Exit code 0 means all tests passed. Non-zero means one or more tests failed — the output will indicate which.

Running All Experiments at Once

If you built from source and have the experiment files in a directory alongside the Simplex source:

# Directory structure expected:
# simplex/          ← the compiler source
#   build/sxc       ← compiled compiler
#   runtime/standalone_runtime.c
# theorem-proof/    ← experiment files
#   exp_contraction.sx
#   exp_lyapunov.sx
#   run_all.sh
#   run_math_tests.sh

cd theorem-proof

# Run 6 core theorem experiments
./run_all.sh

# Run 188 compiler math validation tests
./run_math_tests.sh

Troubleshooting

Understanding .sx Files

Simplex (.sx) files are plain text source code. You can open them in any text editor. Each experiment is self-contained — no imports, no dependencies beyond the compiler and runtime.

Key syntax patterns you'll see:

// Variables: 'let' for immutable, 'var' for mutable
let x: f64 = 3.14;
var count: i64 = 0;

// Functions
fn add(a: f64, b: f64) -> f64 {
    a + b
}

// Loops
while count < 100 {
    count = count + 1;
}

// Output
println("Hello from Simplex");
print_f64(x);

// Entry point — returns 0 for success
fn main() -> i64 {
    // ... experiment code ...
    0
}

For the full language reference, see the Simplex documentation.

Complete Experiment Index

Core Theorem Validation

Cognitive / Belief System

Cross-Domain Applications

Stress Tests and Robustness

Compiler Math Validation

Total: 188/188 pass.