# shunqiang-feng/beamformer architecture

> Architecture diagram of the GitHub repository shunqiang-feng/beamformer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shunqiang-feng/beamformer
- Repository: https://github.com/shunqiang-feng/beamformer

## Overview

BeamFormer reconstructs a full beam-direction RSS spectrum from a small set of reference-beam measurements. Its deployment workflow generates reference weights, obtains RSS measurements, estimates the spectrum, optionally corrects its amplitude, and selects the strongest direction. Training uses CSI data in a joint generator/estimator stage followed by ARN training; the README also documents spectrum visualization and baseline CDF comparison. The excerpts show core model, dataset, and inference wiring; links for unsampled training and visualization internals are limited to documented behavior.

Main entry points: [`beamformer/inference_helper.py`](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/inference_helper.py) (Inference Pipeline), [`beamformer/weight_generator.py`](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/weight_generator.py) (Beam Generator), [`beamformer/train.py`](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/train.py) (Joint Trainer), [`beamformer/dataset.py`](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/dataset.py) (CSI Processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["CSI and Beam Physics"]
  node_csi_files[("CSI Dataset<br/>[dataset.py]")]
  node_dataset_pipeline["CSI Processing<br/>[dataset.py]"]
  node_array_physics["Array Physics<br/>[utils.py]"]
end

subgraph group_models["Beam Models"]
  node_generator["Beam Generator"]
  node_weight_transform["Weight Transform"]
  node_estimator["Spectrum Estimator<br/>[modules.py]"]
  node_perceiver["Perceiver IO<br/>[perceiver_io.py]"]
  node_arn["Amplitude Recovery<br/>[modules.py]"]
end

subgraph group_training["Model Training"]
  node_co_train_config["Co-train Config<br/>[co_train.py]"]
  node_arn_config["ARN Config<br/>[arn.py]"]
  node_shared_config["Shared Config<br/>[submodules.py]"]
  node_co_trainer["Joint Trainer<br/>[train.py]"]
  node_arn_trainer["ARN Trainer<br/>[train_ARN.py]"]
end

subgraph group_inference["Inference and Evaluation"]
  node_inference_helper["Inference Pipeline"]
  node_rss_measurement["Reference RSS"]
  node_spectrum["Predicted Spectrum"]
  node_beam_selection["Beam Alignment"]
  node_spectrum_visualizer["Spectrum Visualization"]
  node_cdf_evaluation["CDF Evaluation<br/>[cdf_plot.py]"]
  node_baseline_results[("Baseline Results")]
end

node_base_station(("Base Station"))

node_csi_files -->|"loads CSI"| node_dataset_pipeline
node_dataset_pipeline -->|"uses array model"| node_array_physics
node_co_train_config -->|"selects settings"| node_shared_config
node_arn_config -->|"selects settings"| node_shared_config
node_co_trainer -->|"loads training data"| node_csi_files
node_co_trainer -->|"prepares RSS"| node_dataset_pipeline
node_co_trainer -->|"optimizes"| node_generator
node_co_trainer -->|"optimizes"| node_estimator
node_arn_trainer -->|"trains"| node_arn
node_arn_trainer -->|"uses pretrained"| node_generator
node_inference_helper -->|"loads processing"| node_dataset_pipeline
node_inference_helper -->|"runs"| node_generator
node_inference_helper -->|"transforms weights"| node_weight_transform
node_inference_helper -->|"runs"| node_estimator
node_inference_helper -->|"applies correction"| node_arn
node_estimator -->|"delegates attention"| node_perceiver
node_base_station -->|"requests reference weights"| node_generator
node_generator -->|"provides weights"| node_base_station
node_base_station -->|"measures reference RSS"| node_rss_measurement
node_rss_measurement -->|"supplies measurements"| node_inference_helper
node_inference_helper -->|"returns spectrum"| node_spectrum
node_spectrum -->|"selects strongest direction"| node_beam_selection
node_spectrum_visualizer -->|"runs inference"| node_inference_helper
node_cdf_evaluation -->|"evaluates model"| node_inference_helper
node_cdf_evaluation -->|"loads baselines"| node_baseline_results

click node_csi_files "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/dataset.py"
click node_dataset_pipeline "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/dataset.py"
click node_array_physics "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/utils.py"
click node_generator "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/weight_generator.py"
click node_weight_transform "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/weight_generator.py"
click node_estimator "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/modules.py"
click node_perceiver "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/perceiver_io.py"
click node_arn "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/modules.py"
click node_co_train_config "https://github.com/shunqiang-feng/beamformer/blob/release/configs/co_train.py"
click node_arn_config "https://github.com/shunqiang-feng/beamformer/blob/release/configs/arn.py"
click node_shared_config "https://github.com/shunqiang-feng/beamformer/blob/release/configs/submodules.py"
click node_co_trainer "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/train.py"
click node_arn_trainer "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/train_ARN.py"
click node_inference_helper "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/inference_helper.py"
click node_spectrum_visualizer "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/visualize_spectrum.py"
click node_cdf_evaluation "https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/cdf_plot.py"
click node_baseline_results "https://github.com/shunqiang-feng/beamformer/blob/release/baselines_result/all_performance_dict.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_csi_files,node_dataset_pipeline,node_array_physics toneBlue
class node_generator,node_weight_transform,node_estimator,node_perceiver,node_arn toneAmber
class node_co_train_config,node_arn_config,node_shared_config,node_co_trainer,node_arn_trainer toneMint
class node_inference_helper,node_rss_measurement,node_spectrum,node_beam_selection,node_spectrum_visualizer,node_cdf_evaluation,node_baseline_results toneRose
class node_base_station toneIndigo
```

## Components

### CSI and Beam Physics

- [CSI Dataset](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/dataset.py): `beamformer/dataset.py`
- [CSI Processing](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/dataset.py): `beamformer/dataset.py`
- [Array Physics](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/utils.py): `beamformer/utils.py`

### Beam Models

- [Beam Generator](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/weight_generator.py): `beamformer/weight_generator.py`
- [Weight Transform](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/weight_generator.py): `beamformer/weight_generator.py`
- [Spectrum Estimator](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/modules.py): `beamformer/modules.py`
- [Perceiver IO](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/perceiver_io.py): `beamformer/perceiver_io.py`
- [Amplitude Recovery](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/modules.py): `beamformer/modules.py`

### Model Training

- [Co-train Config](https://github.com/shunqiang-feng/beamformer/blob/release/configs/co_train.py): `configs/co_train.py`
- [ARN Config](https://github.com/shunqiang-feng/beamformer/blob/release/configs/arn.py): `configs/arn.py`
- [Shared Config](https://github.com/shunqiang-feng/beamformer/blob/release/configs/submodules.py): `configs/submodules.py`
- [Joint Trainer](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/train.py): `beamformer/train.py`
- [ARN Trainer](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/train_ARN.py): `beamformer/train_ARN.py`

### Inference and Evaluation

- [Inference Pipeline](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/inference_helper.py): `beamformer/inference_helper.py`
- **Reference RSS**
- **Predicted Spectrum**
- **Beam Alignment**
- [Spectrum Visualization](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/visualize_spectrum.py): `beamformer/visualize_spectrum.py`
- [CDF Evaluation](https://github.com/shunqiang-feng/beamformer/blob/release/beamformer/cdf_plot.py): `beamformer/cdf_plot.py`
- [Baseline Results](https://github.com/shunqiang-feng/beamformer/blob/release/baselines_result/all_performance_dict.json): `baselines_result/all_performance_dict.json`

### Other components

- **Base Station**

## Connections

- CSI Dataset → CSI Processing: loads CSI
- CSI Processing → Array Physics: uses array model
- Co-train Config → Shared Config: selects settings
- ARN Config → Shared Config: selects settings
- Joint Trainer → CSI Dataset: loads training data
- Joint Trainer → CSI Processing: prepares RSS
- Joint Trainer → Beam Generator: optimizes
- Joint Trainer → Spectrum Estimator: optimizes
- ARN Trainer → Amplitude Recovery: trains
- ARN Trainer → Beam Generator: uses pretrained
- Inference Pipeline → CSI Processing: loads processing
- Inference Pipeline → Beam Generator: runs
- Inference Pipeline → Weight Transform: transforms weights
- Inference Pipeline → Spectrum Estimator: runs
- Inference Pipeline → Amplitude Recovery: applies correction
- Spectrum Estimator → Perceiver IO: delegates attention
- Base Station → Beam Generator: requests reference weights
- Beam Generator → Base Station: provides weights
- Base Station → Reference RSS: measures reference RSS
- Reference RSS → Inference Pipeline: supplies measurements
- Inference Pipeline → Predicted Spectrum: returns spectrum
- Predicted Spectrum → Beam Alignment: selects strongest direction
- Spectrum Visualization → Inference Pipeline: runs inference
- CDF Evaluation → Inference Pipeline: evaluates model
- CDF Evaluation → Baseline Results: loads baselines