Cascadedocs

Getting started

Quickstart

To run Cascade on Sail without cloning anything, use Get started: name a workspace, paste a Sail API key, and open your app a few minutes later. This page runs the app on your laptop instead.

In this quickstart, we run the Cascade app on your laptop, upload a small stand-in trace, simulate it on two copies of the SM86_RTX3070 config, and download the results.

The simulators here are cascade worker --replay, which replays a recorded Accel-Sim log of BabelStream on an RTX 3070 instead of running Accel-Sim. Every number you see comes from that log, not from the trace you upload. The point is to see the whole loop work before you deploy for real.

Before you start#

You need these on your machine.

Run the loop#

  1. Clone and install.
    bash
    git clone https://github.com/atoniolo76/cascade.git
cd cascade
uv sync

    To get the web UI as well, build it once. The build lands in cascade/static/, which the app serves.

    bash
    (cd web && npm ci && npm run build)
  2. Start the app. This runs the API and UI on port 8000 and the S3 endpoint on port 9000. Leave it running and open a second terminal for the next steps.
    bash
    export CASCADE_TOKEN=dev-token
CASCADE_DATA_DIR=./data \
CASCADE_ACCELSIM_DIR=$PWD/tests/fixtures/accelsim \
CASCADE_SIM_CMD="$PWD/.venv/bin/cascade worker --replay $PWD/tests/fixtures/logs/babelstream_sm86_rtx3070.log" \
uv run cascade serve

    When the app is up, the log ends with this line.

    text
    INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
  3. Make a stand-in trace. The replaying worker only checks that traces/kernelslist.g exists, so one line is enough. A real trace comes from the profiler. See Trace a workload.
    bash
    export CASCADE_TOKEN=dev-token CASCADE_URL=http://127.0.0.1:8000
mkdir -p demo/traces
echo kernel-1.traceg > demo/traces/kernelslist.g
  4. Upload it. scripts/upload_trace.py uploads a directory the same way the profiler does and sends metadata.json last. The two --meta flags tell the app which GPU architecture the trace is for and which config to suggest.
    bash
    uv run python scripts/upload_trace.py demo --run-name demo \
  --meta trace_gpu_arch=sm_86 --meta suggested_sim_config=SM86_RTX3070

    You see each file go up.

    text
    uploaded traces/kernelslist.g (16 bytes)
uploaded metadata.json (1 files listed) to s3://cascade/accelsim-traces/demo/
  5. Wait for the trace to be ready. The app scans the bucket every 2 seconds. Because the upload already has kernelslist.g, it skips post-processing.
    bash
    curl -s -H "Authorization: Bearer $CASCADE_TOKEN" "$CASCADE_URL/api/traces/demo"

    Repeat until the response has "state":"ready". It takes a few seconds.

  6. Launch a run. This asks for two sims on SM86_RTX3070 and saves the run's id.
    bash
    RUN=$(curl -s -X POST "$CASCADE_URL/api/runs" \
  -H "Authorization: Bearer $CASCADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trace_id": "demo", "entries": [{"gpu_config": "SM86_RTX3070", "count": 2}]}' \
  | python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])')
echo $RUN
  7. Watch it finish. Each sim replays about 10,000 log lines and finishes in a few seconds.
    bash
    curl -s -H "Authorization: Bearer $CASCADE_TOKEN" "$CASCADE_URL/api/runs/$RUN" \
  | python3 -c 'import json, sys; r = json.load(sys.stdin); print(r["state"], r["sim_counts"])'

    When both sims are done, you see this.

    text
    succeeded {'succeeded': 2}

    If you built the UI, open http://127.0.0.1:8000, paste dev-token, and open the run to see the same thing live.

  8. Download the results. This saves one JSON file with the run, the trace, every sim's per-kernel stats, and the comparison.
    bash
    curl -s -OJ -H "Authorization: Bearer $CASCADE_TOKEN" "$CASCADE_URL/api/runs/$RUN/results"

    The file is named <run id>-results.json. Reading results explains what's in it.

To stop, press Ctrl+C in the first terminal. The app stops rclone too. Your traces and runs stay in ./data for next time.

Next steps#

esc