API reference

Types

This page is generated from cascade/models.py each time the docs build, so it matches the code. The web UI mirrors the same types in web/src/api/types.ts.

Types are Python annotations as written in the source. X | None means the field is always present and may be null. datetime is an ISO 8601 string in UTC. tuple[int, int, int] is a JSON array of three integers.

States#

`TraceState`#

value	meaning
`uploading`	Files are arriving. `kernel_count` and `bytes` grow on each scan, every 2 seconds.
`processing`	The upload is complete. The app is running the trace post-processor, unless the upload already has `traces/kernelslist.g`.
`ready`	Post-processing produced `traces/kernelslist.g`. Runs can launch.
`failed`	`metadata.json` has `status: "failed"`, or post-processing failed. `error` says which.

`SimState`#

value	meaning
`pending`	Created with the run. Waiting for the launcher.
`launching`	The launcher is starting the sim's sandbox or process.
`running`	The sim sent a `running` heartbeat.
`lost`	No heartbeat for `CASCADE_HEARTBEAT_TIMEOUT_S`. A later heartbeat brings it back.
`succeeded`	The sim sent a `succeeded` heartbeat. Terminal.
`failed`	The sim sent a `failed` heartbeat, the launcher failed, or it stayed `lost` for 10 times the timeout. Terminal.
`cancelled`	The run was cancelled before this sim finished. Terminal.

`RunState`#

cascade/models.py

RunState = Literal["active", "succeeded", "partial", "failed", "cancelled"]

value	meaning
`active`	At least one sim has not finished.
`succeeded`	Every sim succeeded.
`partial`	Every sim finished, at least one succeeded, and at least one did not.
`failed`	Every sim failed.
`cancelled`	Every sim finished, at least one was cancelled, and none succeeded.

RunState is not stored. run_state() in cascade/models.py derives it from the run's sim states each time a run is read.

Traces#

`GpuConfig`#

field	type	description
`name`	`str`	Accel-Sim tested-cfgs directory name, e.g. "SM90_H100".
`arch`	`str`	For example, "sm_90".
`core_clock_mhz`	`float`	First value of -gpgpu_clock_domains in gpgpusim.config.

`KernelLaunch`#

One kernel launch from the trace's stats_ctx_* file (original hardware).

field	type	description
`kernel_id`	`int`	Matches kernel-<N> in the trace filename.
`name`	`str`	Mangled kernel name.
`grid`	`tuple[int, int, int]`	Grid size, x, y and z.
`block`	`tuple[int, int, int]`	Block size, x, y and z.
`instructions`	`int \| None`	Instructions the tracer counted. `null` if the kernel's trace was cut short.

`TraceSummary`#

field	type	description
`id`	`str`	The profiler's run_name.
`state`	`TraceState`	Where the trace is in its lifecycle.
`error`	`str \| None`	Why the trace failed. `null` unless `state` is `failed`.
`created_at`	`datetime`	When the first file of the trace landed.
`updated_at`	`datetime`	When the app last changed this trace.
`model`	`str \| None`	`metadata.json` `model`, such as `facebook/opt-125m`.
`layers`	`list[str]`	`metadata.json` `layers`. Empty if missing or not a list.
`source_gpu`	`str \| None`	metadata.json "gpu".
`trace_gpu_arch`	`str`	metadata.json "trace_gpu_arch", default "sm_90".
`suggested_sim_config`	`str \| None`	`metadata.json` `suggested_sim_config`. The UI preselects it on the New run screen.
`real_gpu_config`	`str \| None`	metadata.json: config of the GPU it was captured on. default `null`
`sample_sim_configs`	`list[str]`	metadata.json: preselected. default `[]`
`sample_set`	`str \| None`	metadata.json: traces compared side by side. default `null`
`kernel_count`	`int`	Traced kernels seen so far.
`bytes`	`int`	Bytes on disk under the trace dir.
`has_real_timing`	`bool`	True when the trace has real per-kernel timings (`real_timing.json`). The profiler does not write them yet.
`has_step_timeline`	`bool`	corrected_timeline.json + kernel_mapping.json are in the trace dir.
`sample`	`bool`	True for the sample trace that `cascade serve` seeds from `samples/` (see Introduction), unless `CASCADE_SAMPLES` is false. It is `ready` but has no instruction traces, so it can't start a run.

`TraceDetail`#

Every field of TraceSummary, plus these.

field	type	description
`metadata`	`dict \| None`	The trace's `metadata.json`, parsed. `null` until it arrives.
`kernels`	`list[KernelLaunch]`	Kernel launches from the trace's `stats_ctx_*` files, by `kernel_id`. Filled in when the trace becomes `ready`.

Runs and sims#

`RunEntry`#

field	type	description
`gpu_config`	`str`	A `GpuConfig.name` whose `arch` matches the trace's `trace_gpu_arch`.
`count`	`int`	How many sims run this config. at least 1, at most 64

`RunCreate`#

field	type	description
`trace_id`	`str`	A trace in state `ready`.
`entries`	`list[RunEntry]`	One entry per config. Each fans out to `count` sims. at least 1 item

`RunSummary`#

field	type	description
`id`	`str`	Generated, `run-` and 12 hex digits.
`trace_id`	`str`	The trace the run simulates.
`created_at`	`datetime`	When the run was created.
`state`	`RunState`	Derived from the sims. See `RunState`.
`entries`	`list[RunEntry]`	The entries the run was created with.
`sim_counts`	`dict[SimState, int]`	How many sims are in each state. States with no sims are left out.
`sample`	`bool`	True for the sample run seeded with the sample trace. Its results were recorded when the run was made, not in this workspace, and cancelling it changes nothing.
`replay`	`bool`	Replays a sample's recorded Accel-Sim results. default `false`

`RunDetail`#

Every field of RunSummary, plus these.

field	type	description
`trace`	`TraceSummary`	The run's trace.
`sims`	`list[SimSummary]`	Every sim, sorted by `gpu_config` and then `replica`.

`SimSummary`#

field	type	description
`id`	`str`	Generated, `sim-` and 12 hex digits. The simulator receives it as `CASCADE_SIM_ID`.
`run_id`	`str`	The run this sim belongs to.
`gpu_config`	`str`	The config this sim simulates. The simulator receives it as `CASCADE_GPU_CONFIG`.
`replica`	`int`	0-based index within its {gpu_config, count} entry.
`state`	`SimState`	Where the sim is in its lifecycle.
`error`	`str \| None`	Why the sim failed or went `lost`, from a heartbeat or from the app. A `running` heartbeat clears it.
`launcher_ref`	`str \| None`	Sailbox id or local pid.
`created_at`	`datetime`	When the run was created.
`started_at`	`datetime \| None`	The first `running` heartbeat.
`finished_at`	`datetime \| None`	When the sim reached a terminal state.
`last_heartbeat_at`	`datetime \| None`	The last heartbeat. `null` before the first one.
`exit_code`	`int \| None`	From the final heartbeat, when the simulator sent one.
`kernels_done`	`int`	Kernel stats blocks parsed from the log so far.
`kernels_total`	`int`	The trace's kernel count when the run was created.
`current_kernel`	`str \| None`	The kernel named by the last `launching kernel name:` line in the log.
`latest`	`SimMetrics`	The most recent totals parsed from the log.
`log_tail`	`list[str]`	Last 20 lines.

`SimMetrics`#

field	type	description
`gpu_tot_sim_cycle`	`float \| None`	Simulated cycles so far, over every kernel. default `null`
`gpu_tot_sim_insn`	`float \| None`	Simulated instructions so far, over every kernel. default `null`
`gpu_tot_ipc`	`float \| None`	Instructions per cycle so far, over every kernel. default `null`
`sim_rate_ips`	`float \| None`	gpgpu_simulation_rate, instructions/sec. default `null`

Results#

`KernelStat`#

One per-kernel stats block parsed from Accel-Sim output.

field	type	description
`sim_id`	`str`	The sim that ran this kernel.
`kernel_index`	`int`	0-based order of completion within the sim.
`kernel_name`	`str`	The block's `kernel_name`.
`kernel_launch_uid`	`int \| None`	The block's `kernel_launch_uid`.
`gpu_sim_cycle`	`int \| None`	Cycles this kernel took on the simulated GPU.
`gpu_sim_insn`	`int \| None`	Instructions this kernel ran.
`gpu_ipc`	`float \| None`	This kernel's instructions per cycle.
`sim_time_ns`	`float \| None`	gpu_sim_cycle / core_clock_mhz * 1000.
`stats`	`dict[str, float \| str]`	Every "key = value" line in the block.

`ComparisonRow`#

field	type	description
`kernel_index`	`int`	Row position. Kernels are matched by order.
`kernel_name`	`str`	From real timing if present, otherwise from the first sim that finished this kernel.
`real_ns`	`float \| None`	`duration_ns` from real timing. `null` without real timing.
`sim_ns`	`dict[str, float \| None]`	gpu_config -> median sim_time_ns over replicas.

`Comparison`#

field	type	description
`has_real_timing`	`bool`	False until the trace has real timing.
`configs`	`list[str]`	The run's configs, in entry order, without repeats.
`rows`	`list[ComparisonRow]`	One row per kernel position.

`SimResults`#

field	type	description
`sim`	`SimSummary`	The sim as `SimSummary`.
`trace_id`	`str`	The trace the sim ran.
`gpu_config`	`GpuConfig`	The full config. `arch` is `unknown` and the clock is 0 if the config disappeared since the run started.
`kernels`	`list[KernelStat]`	Every kernel the sim finished, with the full `stats` map.
`totals`	`SimMetrics`	Same as `sim.latest`.

`RunResults`#

field	type	description
`run`	`RunSummary`	The run without its trace and sims, which are below.
`trace`	`TraceDetail`	The full trace.
`sims`	`list[SimResults]`	One entry per sim.
`comparison`	`Comparison`	Same as Compare real and simulated time.

`SimStepTimeline`#

field	type	description
`sim_id`	`str`	The sim that sent it.
`gpu_config`	`str`	The sim's config.
`replica`	`int`	The sim's replica.
`simulated`	`dict`	As sent in `StepTimelineUpload.simulated`.
`compare`	`dict \| None`	As sent in `StepTimelineUpload.compare`.

`SimFile`#

An output file a sim uploaded with PUT /api/sims/{id}/files/{name}.

field	type	description
`name`	`str`	Matches FILE_NAME_PATTERN; Accel-Sim's name, plus .gz when the worker gzipped it.
`size`	`int`	Bytes as stored.
`content_type`	`str`	From the name: `text/csv` for `.csv`, `text/plain` for `.txt` and `.log`, `application/json` for `.json`, `application/gzip` for `.gz`, and otherwise a guess, falling back to `application/octet-stream`.
`created_at`	`datetime`	When this version was stored; a re-put replaces the file.

`RunFile`#

Every field of SimFile, plus these.

field	type	description
`sim_id`	`str`	The sim that uploaded the file.
`gpu_config`	`str`	The sim's config.
`replica`	`int`	The sim's replica.

Simulator calls#

`Heartbeat`#

field	type	description
`state`	`Literal["running", "succeeded", "failed"]`	What the simulator reports. Send `running` while working and `succeeded` or `failed` once at the end.
`exit_code`	`int \| None`	Your process's exit code. Send it with the final heartbeat. default `null`
`error`	`str \| None`	A short reason, with a `failed` heartbeat. default `null`

`HeartbeatAck`#

field	type	description
`state`	`SimState`	The sim's state after this heartbeat.
`cancel`	`bool`	True when main cancelled this sim; the simulator must stop.

`LogChunk`#

field	type	description
`seq`	`int`	Per-sim, increasing; a repeated seq is ignored. at least 0
`lines`	`list[str]`	Lines of simulator stdout, without trailing newlines.

`StepTimelineUpload`#

What a sim posts after step timing: cascade simulate and cascade compare output.

field	type	description
`simulated`	`dict`	`cascade simulate` output (simulated_timeline.json), with steps and summary.
`compare`	`dict \| None`	`cascade compare` output (compare.json) against the real timeline.

Events#

`RunEvent`#

cascade/models.py

RunEvent = SnapshotEvent | SimEvent | LogEvent | KernelEvent

One event on the run event stream. The type field says which model it is.

`SnapshotEvent`#

field	type	description
`type`	`Literal["snapshot"]`	Always `snapshot`. default `"snapshot"`
`run`	`RunDetail`	The run as it is at connect time.
`kernels`	`list[KernelStat]`	Every sim's stats with `stats` emptied; full stats are ~30 KB each.

`SimEvent`#

field	type	description
`type`	`Literal["sim"]`	Always `sim`. default `"sim"`
`sim`	`SimSummary`	The sim after a change: state, heartbeat, progress or metrics.

`LogEvent`#

field	type	description
`type`	`Literal["log"]`	Always `log`. default `"log"`
`sim_id`	`str`	The sim the lines came from.
`lines`	`list[str]`	The new chunk, as the simulator sent it.

`KernelEvent`#

field	type	description
`type`	`Literal["kernel"]`	Always `kernel`. default `"kernel"`
`stat`	`KernelStat`	A kernel that just finished, with the full `stats` map.

Sim transitions#

SIM_TRANSITIONS lists every allowed move. The app ignores any other move, whether it comes from a heartbeat or from the app itself. The comment above it in the source says who makes each move.

Allowed sim transitions. Main owns pending/launching/cancelled/lost; heartbeats own the rest.

from ↓ to →	`pending`	`launching`	`running`	`lost`	`succeeded`	`failed`	`cancelled`
`pending`	·	✓	·	·	·	✓	✓
`launching`	·	·	✓	✓	✓	✓	✓
`running`	·	·	·	✓	✓	✓	✓
`lost`	·	·	✓	·	✓	✓	✓
`succeeded`	·	·	·	·	·	·	·
`failed`	·	·	·	·	·	·	·
`cancelled`	·	·	·	·	·	·	·

succeeded, failed and cancelled are TERMINAL_SIM_STATES. Nothing leaves them. Concepts draws the same table as a diagram.

Run state#

run_state() derives a run's state from its sims' states. These rows are computed by calling it during the build.

sim states	run state
`running`, `succeeded`	`active`
`succeeded`, `succeeded`	`succeeded`
`succeeded`, `failed`	`partial`
`failed`, `failed`	`failed`
`cancelled`, `failed`	`cancelled`
`cancelled`, `succeeded`	`partial`
`cancelled`, `cancelled`	`cancelled`

Types

States#

TraceState#

SimState#

RunState#

Traces#

GpuConfig#

KernelLaunch#

TraceSummary#

TraceDetail#

Runs and sims#

RunEntry#

RunCreate#

RunSummary#

RunDetail#

SimSummary#

SimMetrics#

Results#

KernelStat#

ComparisonRow#

Comparison#

SimResults#

RunResults#

SimStepTimeline#

SimFile#

RunFile#