TheRock/rocm-systems/experimental/python/perfxpert/docs/contributing/proven_optimizations.md

Contributing: new proven optimization case

What you're adding

A before/after profiling case with measurable speedup and a citation. The case becomes both (a) a knowledge-base precedent specialists cite and (b) a test fixture that must pass all 5 correctness gates.

File locations

• Entry: perfxpert/knowledge/proven_optimizations.yaml
• Fixture pair: tests/fixtures/proven_optimizations/<id>.baseline.db + .optimized.db + .md

Template

Append to proven_optimizations.yaml:

- id: <lowercase_snake_case>
  bottleneck_type: <compute|memory_transfer|latency|api_overhead|mixed>
  technique: "<short-phrase>"
  description: >
    2-4 sentence description of the pattern.
  measured_speedup_range: [<low>, <high>]      # e.g. [1.25, 1.40]
  source_citation: "<paper/doc/experiment-id>"
  preconditions:
    - {metric: "<name>", op: ">", threshold: <num>}
  failure_modes:
    - "<pitfall 1>"
  fixture_pair:
    baseline_db:    "tests/fixtures/proven_optimizations/<id>.baseline.db"
    optimized_db:   "tests/fixtures/proven_optimizations/<id>.optimized.db"
    description_md: "tests/fixtures/proven_optimizations/<id>.md"

Concrete example

- id: hip_stream_overlap_async_h2d
  bottleneck_type: memory_transfer
  technique: "overlap H2D copies with compute via hipMemcpyAsync"
  description: >
    The baseline trace serialized host-to-device transfers and kernel launches
    on the default stream. The optimized variant moved transfers onto a
    dedicated stream, inserted the required synchronization once at the true
    dependency boundary, and reduced API-visible idle time while preserving
    wall-clock correctness.
  measured_speedup_range: [1.12, 1.28]
  source_citation: "amd-internal:perfxpert-phase10-async-overlap-example"
  preconditions:
    - {metric: "memcpy_percent", op: ">", threshold: 20}
    - {metric: "overhead_percent", op: ">", threshold: 10}
  failure_modes:
    - "Async copies without pinned host memory can add overhead instead of hiding it"
    - "Missing stream synchronization can create correctness bugs that the baseline trace did not have"
    - "Tiny transfers may not amortize stream-management cost"
  fixture_pair:
    baseline_db:    "tests/fixtures/proven_optimizations/hip_stream_overlap_async_h2d.baseline.db"
    optimized_db:   "tests/fixtures/proven_optimizations/hip_stream_overlap_async_h2d.optimized.db"
    description_md: "tests/fixtures/proven_optimizations/hip_stream_overlap_async_h2d.md"

This example is intentionally small but realistic: it shows the level of specificity reviewers expect for technique naming, conservative speedup ranges, and failure modes.

Fixture construction

Use tests/fixtures/proven_optimizations/_build_fixtures.py as the reference implementation. Synthetic SQLite fixtures must:

• Be < 1 MB each
• Follow rocpd UUID-based schema (see CLAUDE.md §SQLite + rocpd)
• Produce metrics that satisfy your declared preconditions on baseline
• Show the claimed speedup on optimized
• Be regeneratable from the script (commit the generator alongside the .db)

Schema constraints (CI-enforced)

• Schema validation: tests/test_knowledge/test_proven_optimizations.py
• All 5 gates: tests/test_integration/test_proven_optimizations.py
• False-positive rate: regression gate ≤ 5% across the corpus

Tests you must add

The parametrized tests already iterate every case — just add the YAML entry

• the fixture pair and the corpus tests will exercise your case.

Review requirements

• 1 core reviewer
• CI green (schema + integration + gate cascade)
• Measured speedup citation is verifiable (paper link, in-house experiment ID, or AMD doc ref)

Common pitfalls

• Fixture counter names must match knowledge/counter_catalog.yaml
• Failure_modes are load-bearing — a case with no failure_modes is incomplete
• measured_speedup_range is inclusive; keep it conservative — outliers are not the median
• Prefer smaller synthetic fixtures to real traces unless you're comfortable shipping real kernel names

Related docs

• Spec §6.5 (proven optimization case studies)
• tests/fixtures/proven_optimizations/_build_fixtures.py (reference generator)