How-to Guides¶

Warning

Pre-implementation. These guides describe the target surface. Commands and workflows are proposed; the package does not yet exist. Use these pages as a design preview.

How-to guides answer task questions: “I want to do X; what are the steps?” They are not the place for concepts, API signatures, config-field inventories, or design rationale. Each guide should start from a concrete user intent, list prerequisites, show the shortest working path, then cover verification, troubleshooting, and links to reference material.

Current Guides¶

User intent	Guide	Status
Generate a small dataset locally	Generate a small local dataset	Exists
Modify a shipped scenario	Modify a scenario preset	Exists
Choose AWGN, TorchSig, Sionna statistical, or Sionna RT channels	Choose a channel chain	Exists
Configure multi-receiver output layout	Configure multi-RX output	Exists
Generate a production-scale dense urban dataset	Generate a dense urban dataset	Exists
Inspect distributions, samples, and errors	Inspect and audit a dataset	Exists
Resume after worker, quota, or annotation failures	Resume or repair a partial run	Exists
Export to training or interchange formats	Export or convert a dataset	Exists
Add a new waveform source	Add a custom emitter	Exists
Add a new channel transformation	Add a custom channel transformation	Exists
Add a structured-label modality	Add a custom labeler	Exists
Add a time- or frequency-placement strategy	Add a custom placement strategy	Exists
Add a text annotation variant	Add a custom annotation template	Exists
Add an inference-grounded annotator implementation	Add a custom annotator	Exists
Add a storage backend	Add a custom store	Exists
Run large generation jobs on Spark	Run on Spark	Exists
Add or refresh text annotations after Phase 1	Annotate an existing dataset	Exists

Related reference-adjacent page: Scenario presets is the catalog of shipped presets. Use Modify a scenario preset for the task workflow.

Recommended Organization¶

Organize How-to pages by what the user is trying to accomplish:

Group	User question	Pages
Generate	“How do I make a dataset?”	local prototype, preset-based generation, dense urban production
Configure	“How do I change the scene?”	modify a preset, choose channels, configure multi-RX, add geometry
Extend	“How do I add new behavior?”	custom emitter, custom channel, custom labeler, custom placement strategy, annotation template, custom annotator, custom store
Operate	“How do I run and recover jobs?”	Spark, resume a partial run, inspect failures, cost controls
Consume	“How do I use the output?”	inspect/audit, export formats, training handoff
Annotate	“How do I add text supervision?”	annotate existing dataset, revise templates, switch providers

Guide Template¶

Use this shape for every How-to page:

Goal: one sentence describing the task outcome.
When to use this: scope and non-goals.
Prerequisites: installed extras, credentials, existing dataset, or prior guide.
Minimal command path: the shortest working command or config.
Verify: how to confirm the result is correct.
Troubleshoot: common failure modes and recovery commands.
Next steps: adjacent task guides and reference pages.