Metadata-Version: 2.4
Name: cascade-profiler
Version: 0.1.0
Summary: GPU workload tracing and baseline/profiled timeline reconciliation
Project-URL: Repository, https://github.com/atoniolo76/cascade
Project-URL: Documentation, https://github.com/atoniolo76/cascade/blob/profiler/PROFILER_RUNS.md
Project-URL: Issues, https://github.com/atoniolo76/cascade/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Benchmark
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: modal
Requires-Dist: modal; extra == "modal"
Requires-Dist: boto3>=1.36; extra == "modal"
Provides-Extra: vllm
Requires-Dist: vllm==0.21.0; extra == "vllm"
Requires-Dist: nvtx; extra == "vllm"

# Cascade Profiler

GPU workload profiling, Nsight Systems timing reconciliation, and NVBit instruction
tracing for vLLM. Python 3.10+ can import and inspect runs; GPU workloads require
CUDA, vLLM, and the tracing tools. Modal images use Python 3.12.

```sh
pip install 'cascade-profiler[modal]'
```

```python
from cascade_profiler import Workload, profile

workload = Workload("facebook/opt-125m", ["Hello, my name is"], max_tokens=32, repeats=4)
result = profile(workload, "/data/phases", trace_steps="plan", trace_repeat=1)
print(result.run_dir, result.stage_wall_s)
```

`profile` needs a GPU environment with vLLM, Nsight Systems and the NVBit tracer
installed. `cascade_profiler.image()` supplies the optional Modal GPU image;
`register(app, volume, gpu="H100!")` registers only the GPU `.profile` function.
See [PROFILER_RUNS.md](PROFILER_RUNS.md) and [examples/modal_app.py](examples/modal_app.py).

## Profile, then simulate

From this checkout:

```sh
modal run accelsim_trace.py::e2e_main --run-name my-run --trace-steps plan
# Timing only (no CPU simulator image is built):
modal run accelsim_trace.py::e2e_main --run-name timing-run --timing-only
```

Accel-Sim CPU execution lives in the separate `cascade.sim` simulator package on
the `simulator` branch of [atoniolo76/cascade](https://github.com/atoniolo76/cascade).
From that checkout, using the same Modal volume:

```sh
modal run scripts/simulate_accelsim.py --run-name my-run --gpu-config SM90_H100 --propagate interp
```

The run directory is the interface: `run.json`, `corrected_timeline.json`,
`trace_alignment.json`, and `traced/traces/` are produced by the profiler. The
simulator consumes them and writes `sim_durations.json` and `sim/`.
The profiler does not build or execute the CPU simulator.
