pp-simulator-design

name	pp-simulator-design
description	Use when working on pp-simulator code, tests, web UI, trace export, Monte Carlo reports, or dependency modeling for pp-scheduler plans and BigMac pipeline timelines.

PP Simulator Design

Overview

Use this skill to keep pp-simulator changes aligned with its role as a downstream application of pp-scheduler.

The scheduler creates a legal plan. The simulator reads that plan, samples operation durations, rebuilds the realized timeline from dependencies, and helps users understand pipeline behavior through traces, metrics, and web visualization.

Boundaries

• pp-simulator may import pp-scheduler.
• pp-scheduler must not import pp-simulator.
• The simulator should not regenerate or reorder the schedule plan.
• The simulator should filter IDLE and communication operators unless a task explicitly adds communication simulation.
• The web UI should render SimulationResult.ops, not Chrome Trace JSON, because the simulation result contains wait time, dependencies, and dependency reasons in a more useful shape.

Dependency Modeling

Preserve these invariants:

• Rank-local order is always a hard constraint.
• LLM forward depends on the previous PP rank, or on the previous VPP chunk at rank 0.
• LLM backward depends on the next PP rank, or on the next VPP chunk at the last rank.
• LLM backward also depends on its matching forward activation on the same rank.
• VE forward readiness is unit-based: LLM rank 0 chunk 0 waits for all VE forwards in the PP-sized unit.
• VE backward readiness is unit-based: VE backward waits for rank 0 LLM backward of the unit.
• Generator forward waits for the LLM output unit.
• Generator backward only consumes its matching generator forward activation on the same rank and microbatch. Do not add artificial cross-rank GF-to-GB dependencies unless communication simulation is being added explicitly.
• Last-rank LLM backward waits for generator backward gradients for the unit.

When adding or changing a dependency, add or update a unit test that asserts the specific dependency reason.

Trace Export

• Keep standard Chrome Trace event names close to scheduler labels, such as F3-C0.
• Keep Perfetto-compatible names unique enough for Perfetto UI to display all slices reliably, currently rank{rank}/{op}/chunk_{letter}/mb{microbatch}.
• Preserve the original scheduler label in event args.
• Use chunk letters (chunk_a, chunk_b) in categories to make Perfetto colors easier to distinguish.

Web UI

• Keep the first screen as the actual simulator tool.
• Show duration inputs only for op types used by the selected scheduler.
• Render wait gaps separately from compute rectangles.
• Provide hover details and selected-op dependency explanations.
• Keep trace downloads available for external inspection.

Validation Checklist

Before finishing simulator work:

• Run python -m unittest discover -s tests.
• Run python -m compileall pp_simulator examples tests web.
• Run node --check web/static/app.js when frontend code changes.
• For dependency changes, inspect at least one representative UnifiedBigMacVPP plan with pp_size=4, vpp_size=2.