# Optimize Compute

> Profiles the rocprof-compute source CLI in the current worktree using Scalene's CPU-only mode, interprets CPU hotspots, and supports agent-led before/after comparison. Use when a user asks to profile rocprof-compute, optimize a subcommand (profile/analyze/etc.), find CPU bottlenecks, or compare optimization results.

- Skill: `abchoudh-amd/optimize-compute` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add abchoudh-amd/optimize-compute`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abchoudh-amd/optimize-compute/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: abchoudh-amd (https://skillmd.com/u/abchoudh-amd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/abchoudh-amd/optimize-compute

---


# Optimize Compute

Profile the rocprof-compute source CLI with Scalene, interpret bottlenecks, and
deliver actionable recommendations.

This skill runs the script directly from the worktree's `src/` tree — no build
or install step is required. The sibling `build-compute` skill is unrelated.

## Quick start

```bash
bash <SKILL_DIR>/scripts/optimize-compute.sh --label baseline -- profile -n smoke -- ./gpu-burn
```

Replace `<SKILL_DIR>` with the absolute path to this skill directory. Anything
after `--` is forwarded verbatim to rocprof-compute.

## Entry gate (mandatory)

Before invoking the helper, the agent MUST know two things:

1. The rocprof-compute **subcommand** to profile (`profile`, `analyze`, `database`, ...).
2. A **representative workload** for that subcommand — the args after the
   subcommand, including any `-p <workload-path>`, `-n <name>`, target binary,
   or input arguments.

If either piece is missing or ambiguous in the user's prompt, invoke the
`grill-me` skill first to collect:

- subcommand
- workload command/inputs (small enough to finish quickly under Scalene)
- label for this run (`baseline` vs `optimized`, etc.)
- any Scalene tuning flags (e.g. `--cpu-percent-threshold`)

Only invoke the helper once these are pinned down.

## Profiling workflow

Run from the rocprof-compute worktree root (so `src/rocprof-compute` is
auto-discovered):

```bash
bash <SKILL_DIR>/scripts/optimize-compute.sh --label <name> -- <subcommand> <args>
```

To forward Scalene tuning flags use `--scalene-arg` (repeatable):

```bash
bash <SKILL_DIR>/scripts/optimize-compute.sh \
    --label optimized \
    --scalene-arg --cpu-percent-threshold --scalene-arg 0.5 \
    -- analyze -p workloads/smoke
```

To point at a different worktree or a non-standard entry path use
`--source-dir` / `--entry`. See [REFERENCE.md](REFERENCE.md).

The helper:

- Validates Scalene is installed (prompts to `pip install scalene` if not).
- Resolves `src/rocprof-compute` (or `src/rocprof-compute.py`) under
  `--source-dir`.
- Runs Scalene with `--json --cpu-only` defaults plus any `--scalene-arg`
  values.
- Saves output to `.scalene-profiles/<label>.json` and validates it.

## Comparison workflow

1. Profile current code: `--label baseline`
2. User applies a change.
3. Profile again: `--label optimized`
4. Compare:

```bash
bash <SKILL_DIR>/scripts/optimize-compute.sh --compare baseline optimized
```

This validates and prints both JSON paths; it does not calculate deltas. Read
both reports, then compare line-level CPU metrics:

- Delta in `cpu_percent_python` and `cpu_percent_c` per hotspot
- Delta in `cpu_percent_system` where system-call overhead is material
- Delta in `elapsed_time_sec` for the identical representative workload
- Report which hotspots improved, regressed, or are new

## Interpretation rules

Classify each hotspot by its dominant metric:

- **CPU-bound (Python)**: high `cpu_percent_python` — algorithmic improvements,
  vectorization, caching.
- **CPU-bound (native)**: high `cpu_percent_c` — faster library alternative or
  reduced call frequency.
- **System-heavy**: high `cpu_percent_system` — excessive system calls,
  synchronization, or process/file overhead.
- **I/O-bound**: low CPU % relative to wall time — Scalene does not directly
  measure I/O wait, so report this only as a hypothesis requiring another
  profiler.

## Report template

1. **Executive Summary** — one-line verdict: "rocprof-compute `<subcommand>` is
   [type]-bound, spending [X]% in [file:line]"
2. **Top Hotspots** — table: Rank | File:Line | Metric | % of Total | Type
3. **Bottleneck Classification** — group hotspots by type.
4. **Recommendations** — specific change per hotspot with file:line and
   expected impact.
5. **Next Steps** — re-profile command and remaining opportunities.

## Additional resources

- [REFERENCE.md](REFERENCE.md) — flag contract, Scalene forwarded flags, JSON schema, limitations.
- [EXAMPLES.md](EXAMPLES.md) — concrete usage scenarios including the grill-me fallback.
- [writing style](../_shared/WRITING-STYLE.md) — normative prose rules and the pre-save self-check for
  every human-read artifact this skill produces.