v2.0 Available on PyPI

Simulate RIS systems before you build them.

Stop wrestling with expensive physical prototypes and fragmented data silos. Waveflow natively combines propagation physics, ML-guided beam sweeping, and link quality analysis into a highly-efficient Python engine. It just works.

Star on GitHub See how it works
interactive_cli — waveflow
# Set up a smart RIS network in seconds.
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°
# Run ML-guided beam prediction
waveflow>sweep ap1 ris1 ue1 60 10 --algo ml-guided --ml-predictor rf
Initiating ML Prediction... Best Angle Found: 16.5°
2
Channel Engines
(SimRIS & LightRIS)
5+
Beam Sweep
Algorithms
OFDM
Waveform
Simulation
504
Pytest Checks
Verified

The workflow you were going to build

Most research teams ship with physical RIS boards + anechoic chambers + disconnected ML scripts + manual path loss math. That's a lot of overhead. Waveflow is one unified engine.

BEFORE — Physical Hardware & Glue Code
  • Build and maintain expensive physical RIS prototypes.
  • Rely on slow, brute-force blind beam search algorithms.
  • Calculate FSPL, attenuation, and Rician fading manual.
  • Write custom Python glue code to connect your ML models to your physics math.
  • Weeks of setup time, difficult to gather synthetic data for ML, hard to reproduce results.
AFTER — One Python Library
  • Waveflow — Virtual 2D/3D node placement with walls and obstacles.
  • Waveflow — Dual channel engines (Stochastic SimRIS & Analytical LightRIS).
  • Waveflow — Built-in ML predictors (RF, XGBoost, SVR, KNN, LGBM).
  • Waveflow — Built-in OFDM simulation (Per-subcarrier SNR, PAPR).
  • Waveflow — Rich terminal UI, Interactive CLI, and scriptable Python API.

One import joins them natively. Ship your research, not the plumbing.

Dual Channel Engines: SimRIS & LightRIS

Waveflow is built around two complementary engines. SimRIS provides the reference stochastic channel model, while LightRIS powers fast analytical simulation, beam sweeps, and system-level workflows.

SimRIS Engine

Stochastic / Reference

The reference stochastic channel engine, integrated from published articles to enhance Waveflow. Used by default for connect() scenarios.

  • Best for literature-aligned channel studies and validation.
  • Generates full H/G/D channel tensors for deep physical analysis.
  • Ideal for supported channel-aware single link evaluations.

LightRIS Engine

Analytical / Native

Waveflow's native analytical engine. Built explicitly for high-speed performance and massive scale sweeps.

  • Best for fast system-level evaluation and generating ML datasets.
  • Native, optimal performance for large beam sweeps and feedback loops.
  • Supports advanced beam control and tapering-aware workflows.

The questions you're about to ask

No. While it includes FSPL, Waveflow natively calculates atmospheric absorption, Rician fading, mutual coupling, RIS array gain, and phase quantization loss (1–4 bit) out of the box.
SimRIS is the reference stochastic channel engine, integrated from published IEEE articles to enhance Waveflow and support literature-aligned channel studies. LightRIS is our native analytical engine built for fast system-level evaluation, ML dataset generation, and large beam sweeps.
No. They are complementary. SimRIS handles literature-aligned reference channel evaluation, while LightRIS owns fast analytical system workflows such as large sweeps, feedback loops, and ML-oriented experimentation when a full stochastic channel engine would be too heavy.
Yes. Waveflow includes Random Forest, XGBoost, SVR, KNN, and LGBM built-in, but the architecture allows you to easily inject your own custom PyTorch or Scikit-Learn models into the beam sweeping pipeline.
Waveflow already includes built-in ML-guided sweeping workflows and predictors such as Random Forest, XGBoost, SVR, KNN, and LGBM. The project also supports dataset generation and lets you integrate custom learning pipelines when you want tighter control over training and inference.
Yes. Waveflow includes vision-oriented workflow hooks for camera-assisted sweeping and marker-based experiments, alongside synthetic simulation paths. That makes it practical both for pure software experimentation and for hybrid setups where visual feedback helps drive beam selection logic.
Waveflow is not terminal-only. It provides an interactive CLI, a richer modern terminal UI, scriptable Python APIs, scenario-driven execution paths, and reusable components that can be embedded into your own automation or research tooling.
Yes, that is part of the longer-term direction. Today Waveflow is strongest through its terminal and Python workflows, but a richer web-based or GUI experience is planned for the future as the platform matures.
LightRIS is the right engine when you need speed and scale: beam sweeps, tapering-aware evaluation, repeated connect loops, controller design, ML dataset generation, and large batches of system-level experiments.
SimRIS is best when you need a reference stochastic channel model for supported connect scenarios, literature-aligned channel studies, H/G/D tensor analysis, and validation work that should stay close to published RIS-channel formulations.
The current Waveflow branch is backed by hundreds of pytest checks covering connect flows, SimRIS and LightRIS engine behavior, publication-grounded regressions, CLI smoke tests, and physics-level invariants. The public landing page currently advertises 504 verified checks based on the maintained suite inventory.
Yes. That is one of the main reasons to use it. You can place APs, RIS panels, and users virtually, evaluate links, run sweeps, test controller logic, and generate synthetic data before you commit to expensive hardware prototypes or measurement campaigns.
No. The terminal experience is strong, but Waveflow also exposes a scriptable Python API, engine-aware connect flows, scenario runners, and reusable components for integrating your own experiments and automation pipelines.
Not at all. Waveflow is 100% Python. However, we do include an optional MATLAB bridge (`MatlabBridge`) that you can lazy-load if you want to generate 3D far-field beam pattern plots. If you don't have MATLAB, everything else still works flawlessly.

Ship AI wireless products, not plumbing.

Install Waveflow today and start simulating your RIS networks in minutes.

pip install waveflow-sim
Read Documentation