Diffusion Planner

Use this repo skill when a Researcher needs to operate the Diffusion Planner implementation for nuPlan autonomous-driving motion planning. It is a router, not a replacement for the nuPlan devkit or the external dataset/checkpoint artifacts.

Start here

1. Identify the requested stage: data preparation, model training/resume, ordinary closed-loop planning, or custom/guided sampling.
2. Confirm the environment and external inputs before starting an expensive operation. Full training, simulation, and guidance require a CUDA-capable PyTorch environment; real workflows also require nuPlan data/maps and, for inference, a matching args.json plus checkpoint.
3. Run the owning sub-skill's bounded preflight before launching workers, downloading artifacts, or writing a long-running run directory.
4. Preserve the exact model configuration, normalization file, manifest, split, checkpoint, device mapping, and first failure signal in the handoff.

Routes

• data-preparation — convert nuPlan scenarios into fixed-size .npz records and a JSON filename manifest; validate feature axes, paths, and normalization.
• model-training — validate the model/data contract, run bounded PyTorch checks, launch CUDA/DDP training, and resume checkpoints with EMA and optimizer-state caveats.
• closed-loop-planning — configure DiffusionPlanner, trajectory sampling, checkpoint loading, scenario filters/builders, Ray simulation, and optional NuBoard inspection.
• guidance — implement or debug differentiable custom guidance, collision energy, normalization/device handling, and guided simulation.

The usual dependency order is data-preparation → model-training → closed-loop-planning; guidance branches from a compatible planner/checkpoint and then returns to closed-loop-planning for execution.

Installation and environment gate

The source package metadata identifies distribution diffusion_planner at version 1.0.0 and targets Python 3.9. Install the repository package in the active environment, then install the CUDA-aware requirements selected for the workflow. The documented baseline pins PyTorch 2.0.0+cu118 and torchvision 0.15.1+cu118; use a compatible wheel rather than silently substituting a CPU build for a CUDA workflow. Install a matching nuPlan-devkit separately for scenario/map/simulation APIs.

For a checkout of the package, install the public distribution and the workflow-selected requirements in the active environment:

python -m pip install -e .
python -m pip install -r requirements_torch.txt

Install a compatible nuPlan-devkit separately for scenario, map, and simulation APIs. A minimal package import check is:

python -c "import torch, diffusion_planner; print(torch.__version__, torch.cuda.is_available())"

For full preflight, also import the owning modules and run the bundled checks linked by that sub-skill. Do not mutate a shared/base environment merely to repair optional dependencies. Keep external dataset, map, checkpoint, experiment-root, and credentials out of generated skill files and command transcripts intended for publication.

Shared operating rules

• Treat args.json and a checkpoint as a pair. args.json supplies model dimensions and serialized normalizers; a .pth filename alone is not proof of compatibility.
• Keep the model-ready manifest as relative .npz filenames under one data directory. Validate a small sample before DDP or scenario workers start.
• Do not copy the repository's sudo, placeholder, private-interpreter, or eight-GPU shell invocations verbatim. Adapt them to the active environment, visible devices, and approved output paths.
• A parser/import or synthetic tensor check is not a real training or closed-loop result. Report missing data, maps, checkpoints, Ray, or hardware as explicit gates.
• Prefer a tiny, deterministic helper or preflight over an expensive native command. Stop on the first contract failure and route it to the owning sub-skill.
• The implementation has source-backed quirks: the default device is CUDA, DDP floor-divides global batch size without checking divisibility, disabling EMA is not currently flag-only safe, and the scheduler name overstates its post-warmup behavior. Read the model-training references before adapting these paths.

Shared references

• Read repository provenance before deciding whether this skill matches a checkout or needs refresh.
• Read cross-cutting troubleshooting for installation/import, optional dependency, path/config, backend, checkpoint, and external-artifact failures.
• Run the environment probe for a safe import, version, and CUDA diagnostic; it never downloads data or starts simulation.
• Use the generated sub-skill references for API tables, schemas, command details, and difficult-case recovery. Review artifacts and verification reports belong outside this runtime tree.

Stop conditions

Stop and report instead of claiming success when the selected required backend cannot initialize, the package imports only through an unintended checkout, the manifest or normalization contract is invalid, checkpoint/config keys do not match, or external nuPlan data/maps/checkpoints are absent for a requested native run. This graph was generated from commit a3a621f; see provenance for the complete baseline and refresh signals.