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.

PP Simulator Design

Overview

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

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.

pp-simulator-design