KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #ai-agent #claude-code #mcp #typescript #codex #cli #rust #deepseek-harness

ChangShuoRadioData

★ 75 Open GitHub ↗

Wireless Data Tool to collect, annotate, and simulate wireless frame

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Citybuster Studio Logo](https://raw.githubusercontent.com/Singingkettle/ChangShuoRadioData/main/assets/logo.svg)

# ChangShuo Radio Data (CSRD)

[English](README.md) | [Chinese](README.zh-CN.md)

CSRD is a MATLAB spectrum-sensing data generator. Its core promise is simple:
the generated IQ signal, the simulated scene state, and the exported annotation
must describe the same radio event.

The current refactored pipeline is no longer the old "one global frame shape"
design. A run provides policies, each scenario first builds a frozen
`ScenarioPlan`, every frame is generated from that plan, and annotations record
what was planned, executed, and measured.

## Quick Start

**New here? Read [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)** for the full
walkthrough: requirements, OSM map data, the run, the output layout, and
troubleshooting.

In short, from the repository root in MATLAB:

```matlab
addpath(pwd)
addpath(fullfile(pwd, 'tools'))
simulation(1, 1, 'csrd2025/csrd2025.m')
```

Generated data lands under `data/CSRD2025/session_*/` (per-scenario annotation
JSON + IQ `.mat`).

**Before the first run** you need:
- MATLAB **R2025a** with the **Communications**, **Signal Processing**, **Phased
  Array System**, and **Antenna** toolboxes.
- **OSM map data** under `data/map/osm/` — the default config is ~90% OSM ray
  tracing, so an empty map directory fails fast with `CSRD:Scenario:MissingOSMFile`.
  Get it with `pip install requests && python tools/download_osm.py`, or switch to
  the statistical-only channel (`Map.Types = {'Statistical'}`).

See [GETTING_STARTED.md](docs/GETTING_STARTED.md) for details.

## Current Entry Points

| Task | Entry |
| --- | --- |
| Run default generation | `tools/simulation.m` |
| Load a config | `csrd.runtime.config_loader` |
| Orchestrate scenarios/workers | `+csrd/SimulationRunner.m` |
| Generate one scenario | `+csrd/+core/@ChangShuo` |
| Build run policies | `csrd.pipeline.runtime.buildRuntimePlan` |
| Build per-scenario plan | `csrd.pipeline.runtime.buildScenarioPlan` |
| Read annotations | `csrd.pipeline.annotation.readAnnotation` |

Minimal run from the repository root:

```matlab
addpath(pwd)
addpath(fullfile(pwd, 'tools'))
simulation(1, 1, 'csrd2025/csrd2025.m')
```

Generated datasets are written under `data/<DatasetName>/`. The only durable
content expected under `data/` is `data/map/`, which stores local map assets.

## Runtime Model

The production flow is:

```text
config_loader
  -> RuntimePlan          run-level policies and fingerprints
  -> SimulationRunner     scenario dispatch, output, failure accounting
  -> ChangShuo
      -> ScenarioFactory.planScenario
      -> ScenarioPlan     frozen scenario construction plan
      -> frame loop       per-frame execution from the plan
      -> receiver frames  actual signal buffers
      -> annotation    Design / Execution / Measured truth planes
```

Important contracts:

- Raw config stores authorities and policies only.
- `RuntimePlan` is a run-level policy object, not a resolved frame fact store.
- `ScenarioPlan.Frame` owns concrete `FrameNumSamples`,
  `NumFramesPerScenario`, `FrameDurationSec`, and
  `ObservationDurationSec` for one scenario.
- A scenario is generated in three steps: make the plan, execute the plan,
  annotate the actual generated signal.
- `Truth.Design` comes from the scenario plan and blueprint facts.
- `Truth.Execution` comes from actual sample-grid insertion, channel, RF, and
  geometry execution.
- `Truth.Measured` comes from receiver-side measurements of generated signals.

Old raw fields such as `Runner.FixedFrameLength`,
`Factories.Scenario.Global.FrameLength`,
`Factories.Scenario.Global.FrameNumSamples`,
`Factories.Scenario.Global.NumFramesPerScenario`, `FrameDuration`, and
`ObservationDuration` are not compatibility aliases. They are rejected at the
configuration boundary.

## Repository Layout

| Path | Purpose |
| --- | --- |
| `+csrd/` | Main MATLAB package. |
| `+csrd/+core/@ChangShuo/` | Per-scenario engine and per-frame generation helpers. |
| `+csrd/+factories/` | Factory objects for scenario, message, modulation, Tx RF, channel, and Rx RF execution. |
| `+csrd/+blocks/` | Scenario simulators and physical-layer blocks. |
| `+csrd/+pipeline/` | Cross-module contracts for runtime plans, annotation, measurement, link budget, scenario timing, and signal gating. |
| `+csrd/+runtime/` | Config loading, logging, map helpers, performance tracing, toolbox checks, and system info. |
| `+csrd/+catalog/` | Regulatory spectrum catalogs and reusable profile libraries. |
| `+csrd/+support/` | Internal validation, hashing, documentation, random, and maintenance helpers. |
| `config/` | Base configs and public `csrd2025` configs. |
| `tools/` | Public entrypoints, CI gates, audits, diagnostics, visualization, and maintenance scripts. |
| `tests/` | MATLAB unit and regression tests. |
| `docs/` | Current documentation plus archived audit history. |
| `data/map/` | Local OSM/map assets. Do not delete during cleanup. |

See [docs/architecture/source-layout.md](docs/architecture/source-layout.md)
for the current package responsibilities.

## Configuration

Use `config/csrd2025/csrd2025.m` as the default working example. Custom configs
inherit from files under `config/_base_/` through `baseConfigs`.

Current frame diversity is configured with `Factories.Scenario.FramePolicy`:

```matlab
config.Factories.Scenario.FramePolicy.FrameNumSamples.Mode = 'Choice';
config.Factories.Scenario.FramePolicy.FrameNumSamples.Values = [1024, 2048, 4096];
config.Factories.Scenario.FramePolicy.NumFramesPerScenario.Mode = 'IntegerRange';
config.Factories.Scenario.FramePolicy.NumFramesPerScenario.Min = 4;
config.Factories.Scenario.FramePolicy.NumFramesPerScenario.Max = 10;
```

OSM map selection is file-level balanced coverage. There is no default
file-size cap or "large map" exclusion. Large OSM files may be slow because
MATLAB `siteviewer` and `raytrace` must process the map geometry; that is a
performance fact, not a reason to silently skip or downgrade a case.

For configuration details, see [docs/configuration.md](docs/configuration.md).

## Validation

Fast local smoke:

```matlab
addpath(pwd)
addpath(fullfile(pwd, 'tools', 'ci'))
run_csrd_ci_smoke('IncludePhase4', false, 'BaselineScenarios', 1)
```

Useful focused tests:

```matlab
runtests('tests/unit/ScenarioPlanBuildTest.m')
runtests('tests/unit/ScenarioPlanFrozenBeforeFrameExecutionTest.m')
runtests('tests/unit/BuildSourceAnnotationTest.m')
runtests('tests/unit/MeasurementCompletenessHookTest.m')
```

## Documentation

Start here:

- [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md): generate your first dataset
  (requirements, OSM data, the run, the output, troubleshooting).
- [docs/README.md](docs/README.md): documentation index.
- [docs/configuration.md](docs/configuration.md): current configuration and
  runtime-plan contract.
- [docs/annotation-schema.md](docs/annotation-schema.md): annotation
  consumer contract.

Historical refactoring audits, phase notes, and overnight bug-hunt findings are
preserved on the
[`archive/history-2026-06-30`](https://github.com/Singingkettle/ChangShuoRadioData/tree/archive/history-2026-06-30)
branch, not on `main`.

## Citation

If you use ChangShuoRadioData, please cite both the framework and the CSRD2025
dataset paper:

```bibtex
@software{chang_shuo_2025_10667001,
  author       = {Chang, Shuo},
  title        = {ChangShuoRadioData: A Comprehensive MATLAB-based Radio Communication Simulation Framework},
  month        = mar,
  year         = 2025,
  publisher    = {ChangShuoLab},
  version      = {v1.0.0},
  url          = {https://github.com/Singingkettle/ChangShuoRadioData}
}
```

```bibtex
@ARTICLE{11289512,
  author={Chang, Shuo and Sun, Rui and He, Jiashuo and Huang, Sai and Yu, Kan and Feng, Zhiyong},
  journal={IEEE Journal on Selected Areas in Communications}, 
  title={CSRD2025: A Large-Scale Synthetic Radio Dataset for Spectrum Sensing in Wireless Communications}, 
  year={2026},
  volume={44},
  number={},
  pages={2378-2392},
  keywords={Radio frequency;Wireless communication;Sensors;Annotations;Data acquisition;Synthetic data;Interference;Data models;Wireless sensor networks;Emulation;Synthetic radio dataset;spectrum sensing;large AI models},
  doi={10.1109/JSAC.2025.3641910}}
```

> **The JSAC paper describes an earlier version** of this framework, preserved at
> the historical revision
> [`a6d09a4b`](https://github.com/Singingkettle/ChangShuoRadioData/tree/a6d09a4b264894b76f852ce33bfd82adc7b270b5).
> New users should build on the **latest `main`**, not that revision.

### Related work — `twc/` folder only

The IEEE TWC paper below corresponds **only to the [`twc/`](twc/) subfolder and
is independent of the main framework**; cite it only if you use that folder:

```bibtex
@ARTICLE{10667001,
  author={Xing, Huijun and Zhang, Xuhui and Chang, Shuo and Ren, Jinke and Zhang, Zixun and Xu, Jie and Cui, Shuguang},
  journal={IEEE Transactions on Wireless Communications}, 
  title={Joint Signal Detection and Automatic Modulation Classification via Deep Learning}, 
  year={2024},
  volume={23},
  number={11},
  pages={17129-17142},
  keywords={Feature extraction;Signal detection;Frequency modulation;Time-frequency analysis;Signal to noise ratio;Industries;Deep learning;Automatic modulation classification;dataset design;hierarchical classification head},
  doi={10.1109/TWC.2024.3450972}}
```

ChangShuoRadioData

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README