waveflow-sim 2.0.1

Waveflow: RIS-assisted wireless network simulator with beam sweeping, OFDM waveform, ML predictors, and interactive CLI

Waveflow v2.0

Waveflow is a Python simulator for wireless networks assisted by Reconfigurable Intelligent Surfaces (RIS). It lets researchers and engineers model how passive reflective panels improve signal coverage, optimize beam angles, and evaluate link quality — without physical hardware.

Use it to prototype RIS-assisted network topologies, benchmark beam sweeping algorithms, study propagation physics, simulate OFDM waveforms, and run ML-guided beam prediction — through a scriptable Python API, interactive CLI, or modern terminal commands.

Quick Start

pip install waveflow-sim
waveflow

Or install from source:

git clone https://github.com/nqmn/waveflow
cd waveflow
pip install -e .
waveflow

Full installation options: INSTALL.md
Step-by-step tutorials: TUTORIAL.md

Features

Category	Capability
Network	2D/3D node placement (AP, RIS, UE), walls and obstacles, JSON/YAML topology files, random RIS-aware layout generation
Physics	FSPL, atmospheric absorption, Rician fading, mutual coupling, RIS array gain, phase quantization loss (1–4 bit)
Beam sweeping	Linear, coarse-fine, differential evolution, ML-guided, hierarchical, PRIME localization, HOG/ArUco vision
Pathfinding	Dijkstra, A*, Greedy, Exhaustive across multi-hop RIS networks
Waveform	OFDM signal simulation, per-subcarrier SNR, multipath, PAPR, waveform-level vs system-level comparison
Feedback	Closed-loop UE→AP SNR feedback with adaptive beam tracking
ML	Random Forest, XGBoost, SVR, KNN, LGBM, MLP beam angle predictors; trainable from generated datasets
Streaming	Per-chunk BER, SER, throughput, and Shannon capacity over active RIS links
Interface	Interactive CLI, Typer/Rich terminal UI (waveflow ui), Python API, headless scenario runner
Validation	14-section physics validation suite, 66 pytest checks against analytical reference values
MATLAB	Optional bridge for far-field beam pattern plots and phase visualisation

Usage

Interactive CLI

waveflow
waveflow> add ap ap1 0 0
waveflow> add ris ris1 5 0 0 16 2
waveflow> add ue ue1 10 3
waveflow> connect ap1 ris1 ue1
SNR: 29.9 dB   Power: -52.3 dBm   Beam angle: 16.7°
waveflow> sweep ap1 ris1 ue1 60 10 --algo coarse-fine
waveflow> stream ap1 ris1 ue1
waveflow> status
waveflow> save mynet.json
waveflow> help

Key shell commands:

Command	What it does
add ap/ris/ue	Add a node at specific coordinates
add random	Auto-generate a valid AP + RIS + UE layout
connect	Compute SNR, power, and beam angle for a link
sweep	Search for the best beam angle using a chosen algorithm
stream	Simulate a live data stream and measure throughput
status	Show all nodes, distances, and active links
list	Print an ASCII map of the network
links	Show active links only
clear	Remove links or the entire network
save / load	Persist and restore network state to/from JSON
plot	Visualise sweep or connect results (requires [plot])
signal	Detailed per-hop signal breakdown
testall	Run the built-in test suite
testphysics	Run the physics validation suite

Modern Terminal UI

Non-interactive commands with Rich-formatted output — suitable for scripts, CI, and SSH sessions:

# Network status from a topology file
waveflow ui status --topology examples/json/example_1_simple.json

# Connect and get link metrics
waveflow ui connect AP1 R1 UE1 --topology examples/json/example_1_simple.json

# Beam sweep with live progress bar
waveflow ui sweep AP1 R1 UE1 --topology examples/json/example_1_simple.json --fov 60 --step 10

# Run physics validation suite
waveflow ui testphysics

# Run the comprehensive test suite
waveflow ui testall

# Run any legacy CLI command non-interactively
waveflow ui run --topology examples/json/example_1_simple.json signal AP1 R1 UE1 --breakdown

# Open the full interactive shell
waveflow ui shell

# All available commands
waveflow ui --help

Python API

High-level API:

from waveflow import RISnet

net = RISnet()
ap  = net.addAP('ap1',  position=(0, 0))
ris = net.addRIS('ris1', position=(5, 0), N=16, bits=2)
ue  = net.addUE('ue1',  position=(10, 3))
net.start()

result = net.ping(ap, ue)
print(f"SNR: {result['snr_dB']:.1f} dB, hops: {result['hops']}")

throughput = net.iperf(ap, ue)
print(f"Throughput: {throughput['throughput_Mbps']:.1f} Mbps")

net.stop()

Low-level API:

from core import RISNetwork

net = RISNetwork(enable_messaging=False)
net.add_ap('ap1', 0, 0)
net.add_ris('ris1', 5, 0, N=16, bits=2, max_angle_deg=90)
net.add_ue('ue1', 10, 3)

result = net.connect('ap1', 'ris1', 'ue1', use_get_snr=False)
print(f"SNR:        {result['snr_dB']:.1f} dB")
print(f"Beam angle: {result['beam_angle']:.1f}°")
print(f"Array gain: {result['gain_dBi']:.1f} dBi")
print(f"Quant loss: {result['quant_loss_dB']:.2f} dB")

Headless Scenario Runner

Run simulations from JSON or YAML files — no Flask, no interactive shell:

from risnet import ScenarioRunner, ScenarioRequest

runner = ScenarioRunner()

# From a topology file
result = runner.run_connect('examples/json/example_1_simple.json', use_get_snr=False)
print(f"SNR: {result.result['snr_dB']:.1f} dB")

# From a YAML scenario file
request = ScenarioRequest.from_file('scenario.yaml')
result = runner.run(request)

scenario.yaml:

topology_path: examples/json/example_1_simple.json
connect:
  ap_name: ap1
  ris_name: ris1
  ue_name: ue1

Beam Sweep Algorithms

waveflow> sweep ap1 ris1 ue1 60 10 --algo linear
waveflow> sweep ap1 ris1 ue1 60 10 --algo coarse-fine
waveflow> sweep ap1 ris1 ue1 60 10 --algo de
waveflow> sweep ap1 ris1 ue1 60 10 --algo ml-guided --ml-predictor rf
waveflow> sweep ap1 ris1 ue1 60 10 --algo prime

Algorithm	Key	Notes
Linear brute-force	linear	Uniform steps over full FOV
Coarse-fine	coarse-fine	Two-phase search, ~30% fewer evaluations
Differential Evolution	de	Population-based global search
ML-guided	ml-guided	RF / XGBoost / SVR / KNN / LGBM predictor + refinement
Hierarchical	hierarchical	Multi-resolution sweep
PRIME localization	prime	Beam measurement → UE position estimate
DE localization	de-localization	Blind UE localization via DE

Optional Extras

pip install -e ".[plot]"         # matplotlib — enables plot command and charts
pip install -e ".[ml]"           # scikit-learn + torch — ML beam predictors
pip install -e ".[terminal]"     # typer + rich — waveflow ui commands
pip install -e ".[vision]"       # opencv-python — ArUco / HOG vision workflows
pip install -e ".[web]"          # flask + waitress — web interface
pip install -e ".[optimization]" # cvxpy + scs — phase optimization
pip install -e ".[dev]"          # pytest, black, flake8, mypy
pip install -e ".[all]"          # everything above

Vision Integration

The [vision] extra enables two camera-assisted workflows:

ArUco marker positioning — generate printable fiducial markers, detect them from a camera feed, and derive UE position estimates for use as sweep inputs:

pip install -e ".[vision]"
PYTHONPATH=. python3 examples/script/example_18_aruco_markers.py

✓ Successfully saved: aruco_markers/aruco_id_0.png
Generated 5 markers: aruco_markers/batch/aruco_id_{0..4}.png

HOG human detection — use a histogram-of-oriented-gradients detector on a live webcam feed to locate a person and derive a candidate beam direction:

PYTHONPATH=. python3 examples/script/example_19_hog_human_detection.py
# Requires a connected webcam

Vision is example-driven rather than a full CLI product surface. The intended workflow is: detection output → target angle or position → feed into a sweep algorithm as a candidate beam direction.

MATLAB Integration

Waveflow includes an optional MATLAB bridge for far-field beam pattern visualisation. The bridge is lazy-loaded — if MATLAB is not installed, all non-MATLAB functionality continues to work normally.

Standalone MATLAB scripts (no Python required) live in examples/matlab/:

Script	What it shows
example_1_beam_pattern_3d.m	3D far-field beam pattern, 1D/polar cuts, phase heatmap
example_2_compare_steering_angles.m	Side-by-side patterns for 6 steering angles
example_3_ris_phase_farfield.m	Phase maps + 3D far-field (Python-matched parameters)
example_4_ris_phase_farfield_cst_style.m	CST-style annotated 3D pattern with source/beam arrows

Run from the MATLAB command window:

cd examples/matlab
example_1_beam_pattern_3d
example_3_ris_phase_farfield(0, 5.8e9, 0.45, 0, 45, 0, 16, 16)

From Python, the bridge is accessed via MatlabBridge:

from matlab_integration import MatlabBridge
bridge = MatlabBridge.get_instance()   # lazy-loaded; MATLAB starts on first use
bridge.plot_beam_pattern(...)

The library functions under matlab_integration/scripts/ (compute_beam_pattern, plot_ris_geometry, etc.) are called by the Python bridge — they are not intended to be run directly.

Project Structure

waveflow/
├── core/               # Physics, nodes, network manager, waveform, environment
├── controller/         # Beam sweeping, pathfinding, ML predictors, phase control
├── cli/                # Interactive shell (main_shell.py)
├── risnet/             # High-level API, scenario runner (backward-compatible package)
├── waveflow/           # Public package alias (forward-looking name)
├── app/                # Optional Flask web interface
├── config/             # Configuration management
├── utils/              # Link budget, SNR, RSSI, CSI helpers
├── matlab_integration/ # Optional MATLAB bridge for beam pattern plots
├── risformula/         # Standalone formula implementations
├── examples/
│   ├── script/         # 19 runnable Python examples
│   ├── json/           # Topology fixture files
│   └── matlab/         # Standalone MATLAB scripts
├── tests/              # Test suite (pytest)
├── INSTALL.md
├── TUTORIAL.md
└── FUTURE.md           # v3 architecture roadmap

Testing

# Compile check
python3 -m compileall core controller cli risnet waveflow config utils

# Physics regression
PYTHONPATH=. python3 tests/test_physics_fixes.py

# Physics model validation suite (14 sections, 53 checks)
waveflow ui testphysics

# Full test suite via terminal UI
waveflow ui testall

# Full suite with pytest (66 checks including test_physics_core.py)
pip install -e ".[dev]"
pytest tests/ -v

Roadmap

See FUTURE.md for the full v3 architecture migration plan — phased arrays, spatial channels, AI-native runtime, and web interface.

Contributing

Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.

Citation

If you use Waveflow in your research, please cite:

@software{waveflow,
  title  = {Waveflow: Wireless Propagation, Waveform, and RIS-Assisted Network Simulator},
  author = {Mohd Adil},
  year   = {2026},
  url    = {https://github.com/nqmn/waveflow}
}

License

Apache 2.0 — see LICENSE